Welcome to 🗓 date-assistant’s documentation!¶
date-assistant is a Python library that give you classes and functions with intuitive names for common dates operations. Feel free to colaborate and take a look at the repository
Contents¶
Installation¶
To use date-assistant, first install it using pip:
pip install date-assistant
Usage¶
Currently there are 2 approaches for using this package: the Functions approach and the Class approach.
When to use each?¶
Functions approach: When you are going to do a single operation with the same dates.
Class approach: When you are going to do multiple operations with the same dates.
Note
💡 Please consider that the default date format is '%Y-%m-%d', eg: '2021-12-25'. Anyways, you can indicate the format of your date if you need to.
Functions approach¶
Get the difference of days between 2 dates¶
First, import get_days_diff_between from date_assistant:
from date_assistant import get_days_diff_between
get_days_diff_between('2021-01-01', '2021-01-11')
# 10
Using the function is every easy. Just pass the dates you want use as parameters:
from date_assistant import get_days_diff_between
get_days_diff_between('2021-01-01', '2021-01-11')
# 10
Note
💡 Please consider that the default date format is '%Y-%m-%d', eg: '2021-12-25'. Anyways, you can indicate the format of your date if you need to.
Maybe the dates you are using have a different format, you can indicate that:
from date_assistant import get_days_diff_between
get_days_diff_between(
'01-01-2021',
'01-11-2021',
date1_format='%d-%m-%Y',
date2_format='%m-%d-%Y',
)
# 10
When indicating the format of a date, it may be hard to remember which is the string that matches the format of the date. Use the format constants which have a more intuitive name for the format of the date:
from date_assistant import get_days_diff_between
from date_assistant.formats import DD_MM_YYYY, MM_DD_YYYY
get_days_diff_between(
'01-01-2021',
'01-11-2021',
date1_format=DD_MM_YYYY,
date2_format=MM_DD_YYYY,
)
# 10
Get the difference of months between 2 dates¶
The same things described for the get_days_diff_between function applies when using get_months_diff_between. You need to import the function, pass the dates as arguments and you can indicate the format of the dates if you need to:
from date_assistant import get_months_diff_between
from date_assistant.formats import DD_MM_YYYY
get_months_diff_between(
'2021-02-14',
'14-02-2022',
date2_format=DD_MM_YYYY,
)
# 12
Note
💡 Notice that we didn’t indicate a format for date1, that’s because date1 has the same format as the default format: %Y-%m-%d.
What happens if we use this function with the last day of a month and the first day of the next one? What do you think the output will be? Let’s take a look:
from date_assistant import get_months_diff_between
get_months_diff_between(
'2021-01-31',
'2021-02-01',
)
# 0
As you can see, we get a 0. Because this function only counts the full months between dates. If you need to know how many months have started between 2 dates, use get_months_started_between.
Get the amount of months started between 2 dates¶
Sometimes you need to know how many months have started between 2 dates. That means that between the last day of a month and the first day of the next one, 1 month started. Let’s look explore that use case in this section.
First, import get_months_started_between from date_assistant:
from date_assistant import get_months_started_between
get_months_started_between(
'2021-01-31',
'2021-02-01',
)
# 1
Using the function is every easy. Just pass the dates you want use as parameters, in this case we are using the last day of a month and the first day of the next one as dates:
from date_assistant import get_months_started_between
get_months_started_between(
'2021-01-31',
'2021-02-01',
)
# 1
See how we get a 1 as result. That’s because a new month started between the dates, in this case february.
Note
💡 This function allows the same parameters as the previous functions we saw. For example, you can indicate the format of the dates.
Get the difference of years between 2 dates¶
The same things described for the get_days_diff_between function applies when using get_years_diff_between. You need to import the function, pass the dates as arguments and you can indicate the format of the dates if you need to:
from date_assistant import get_years_diff_between
from date_assistant.formats import DD_MM_YYYY
get_years_diff_between(
'2021-02-14',
'14-02-2022',
date2_format=DD_MM_YYYY,
)
# 1
Note
💡 Notice that we didn’t indicate a format for date1, that’s because date1 has the same format as the default format: %Y-%m-%d.
What happens if we use this function with the last day of a year and the first day of the next one? What do you think the output will be? Let’s take a look:
from date_assistant import get_months_diff_between
get_years_diff_between(
'2021-12-31',
'2022-01-01',
)
# 0
As you can see, we get a 0. Because this function only counts the full years between dates. If you need to know how many years have started between 2 dates, use get_years_started_between.
Get the amount of years started between 2 dates¶
Sometimes you need to know how many years have started between 2 dates. That means that between the last day of a year and the first day of the next one, 1 year started. Let’s look explore that use case in this section.
First, import get_years_started_between from date_assistant:
from date_assistant import get_years_started_between
get_years_started_between(
'2021-12-31',
'2022-01-01',
)
# 1
Using the function is every easy. Just pass the dates you want use as parameters, in this case we are using the last day of a year and the first day of the next one as dates:
from date_assistant import get_years_started_between
get_years_started_between(
'2021-12-31',
'2022-01-01',
)
# 1
See how we get a 1 as result. That’s because a new year started between the dates, in this case the year 2022.
Note
💡 This function allows the same parameters as the previous functions we saw. For example, you can indicate the format of the dates.
Class approach¶
Get the difference of days, months and years between 2 dates¶
First, import DateAssistant from date_assistant, it will grant you access to all the main methods:
from date_assistant import DateAssistant
my_birthday_2021 = DateAssistant('2021-07-13')
date_assistant_birthday = '2021-08-18'
my_birthday_2021.days_diff_with(date_assistant_birthday)
# 36
my_birthday_2021.months_diff_with(date_assistant_birthday)
# 1
my_birthday_2021.years_diff_with(date_assistant_birthday)
# 0
You don’t actually need to define another variable, but it will improve the readability:
from date_assistant import DateAssistant
my_birthday_2021 = DateAssistant('2021-07-13')
date_assistant_birthday = '2021-08-18'
my_birthday_2021.days_diff_with(date_assistant_birthday)
# 36
my_birthday_2021.months_diff_with(date_assistant_birthday)
# 1
my_birthday_2021.years_diff_with(date_assistant_birthday)
# 0
Now execute the methods to get the answer as an integer:
from date_assistant import DateAssistant
my_birthday_2021 = DateAssistant('2021-07-13')
date_assistant_birthday = '2021-08-18'
my_birthday_2021.days_diff_with(date_assistant_birthday)
# 36
my_birthday_2021.months_diff_with(date_assistant_birthday)
# 1
my_birthday_2021.years_diff_with(date_assistant_birthday)
# 0
You can indicate the format of both of your dates, on the __init__ method for the base date and on each operation method when using another date (exactly as the Functions approach).
Note
💡 Please consider that the default date format is '%Y-%m-%d', eg: '2021-12-25'. Anyways, you can indicate the format of your date if you need to.