Datetime Utility Function

✨ wrappers, utility for datetime module ✨

Attention

The code GitHub Gist is focused towards providing utility functions related to date and time objects. The recommended cloning syntax for the gist is as below:

$ git clone https://gist.github.com/ZenithClown/d2dd294c5f528459e16b139c04c0b182.git dtutils

Datetime Wrapper

A list of utility functions related to datetime objects. The module uses the core datetime module to manipulate “date-time” object, and thus the file is named as datetime_ to distinguish the methods and let the enduser know its capabilities.

datetime_.date_range(start: date, end: date) → Generator

Create an Iterable of Dates between Start and End Date

The pandas has the capability of producing time range, but creates an overhead and also returns a pd.TimeStamp object. To answer this, a simple generator object is defined to return all the dates between a start and a end time period.

import datetime as dt
import datetime_ as dt_ # ? this file, from pythonpath

start, end = dt.date(2023, 1, 1), dt.date(2023, 1, 31)

Given a start date and an end date, the function creates an iterable of all the dates. Simply, the function can be used as an iterator like:

iterable = dt_.date_range(start = start, end = end)
print(next(iterable)) # prints the date

Or, can be encapsulated under inbuilt list method to get the dates as an iterable list:

all_dates = list(iterable)

The pandas module’s “TimeStamp` is also an extension of the “datetime” module and all the methods are valid. To convert the same into a timestamp object:

import pandas as pd
timestamps = list(map(
    lambda x : pd.Timestamp(str(x)), all_dates
))

Parameters:

start (dt.date) – The start from which the date range is to be created (inclusive).
end (dt.date) – The end date till which the date range is to be created (inclusive).

datetime_.fiscal_year(date: date | datetime, start: int = 4, **kwargs) → str

Calculate and Return Fiscal Year from a Date

The function returns the fiscal year from a given date and setting a start month for the fiscal year calculation. This function only uses basic python library to calculate the fiscal year, thus reducing the overhead of other functions.

Parameters:

date (dt.date | dt.datetime) – The date (or date-time) from which the fiscal year is to be calculated.
start (int) – The month from which the fiscal year is to be calculated. Defaults to 4 i.e., April month.

Keyword Argument(s)

The typical keyword arguments are generally to format the output string formatting.

prefix (str): The prefix for the output string,
defaults to “F.Y. ” value.

seperator (str): The separator between the prefix
and the year, defaults to “-” value.

shorten (bool): The flag to shorten the next year
value to two digits, or full value, defaults to True value.

Example Usage

The input in always expected to be an instance of dt.date or dt.datetime object. The function returns the fiscal year as:

import datetime as dt
import datetime_ as dt_

date = dt.date(2023, 1, 1)
print(dt_.fiscal_year(date)) # fiscal year, default settings
>> F.Y. 2022-23

print(dt_.fiscal_year(date, start = 1, shorten = False))
>> F.Y. 2023-2024

datetime_.get_date(current: date | None = None, n: int = -1, mode: str = 'last') → date

A Simple Wrapper of the dt.timedelta to get Dates

The function returns date of “first”/”last” date of “n”-months forward/backward based on the required parameters as below:

Parameters:

current (object) – The starting date of calculation, which is typically the current date. Defaults to current date, i.e., dt.datetime.now().date() which is caluctated.
n (int) – Number of months for which the last or first day is required. Defaults to -1 i.e., last month. If the value is positive then the function is forward looking while a negative value is backward looking.
mode (str) – Type of return value which is either the “first” day or the “last” day of the month, defaults to “last”.