Date
To start working with the module you can run the following import statement, which will be used through the entire module:
Properties¶
The Date module contains a couple of useful properties for retrieving information about the date such as month name, day name, current week of the year, and a few more.
Month Name and Day Name¶
Imagine that we have a Date object and we wish to extract name of both day and month, we can achieve this by making use of the day_name and month_name property:
Numerical Properties¶
There is also the option of extracting numerical quantities such as the current week of the year:
We are also able to extract the current day of the year out of the full 365 days:
Lastly, when working with months we have the possibility of retrieving the current week of the month:
And also the current quarter of the year:
Getting Today's Date¶
Use Date.today() to get the current date as a Date object:
Formatting a Date¶
The strftime() method formats a Date object as a string using standard format codes:
Retrieving Dates¶
The Date class offers a variety of methods that are useful for checking whether a specific date falls under a certain condition or simply retrieving a date based on the condition.
All methods accept a bizdays boolean which indicates whether to consider business days or not, and a calendar string for referencing holidays.
Get First Day of¶
The methods below are used in order to retrieve the first date of a given week, month, quarter, or year.
Week
Month
In the case of wanting to include business days:
In our first month example we got the first day of September which falls on a Sunday, and since we want to include business days, our original date got moved 1 day.
Quarter
Year
Let's specify a calendar for a change.
Again, in our last example we are highlighting the difference in the outputs when it comes to using a specific calendar.
Get Last Day of¶
Opposing our initial "get first" methods, we also have the option of retrieving the last day of a given week, month, quarter, or year.
Week
Month
Quarter
Year
Condition Checking¶
Now, instead of returning dates we will be checking whether a given date is the first or last day of a week, month, quarter, or year, then return a boolean value indicating that.
As an important reminder, all methods still accept the bizdays and calendar as inputs, following the same logic as before.
Is First Day of¶
Putting it simply, all the methods below are used to check whether a given date is the first day of a week, month, quarter, or year.
Week
Using our current date example, at first we see that the date does not correspond to the beginning of the week. However, the scenario changes if we consider business days:
Month
Quarter
Year
Is Last Day of¶
Finally, since we have ways of checking if a date is the first day of a week, month, quarter, or year, it is only fair to have the option of checking if a date is the last day of a given period.
Week
Month
Quarter
Year
Running Operation on Dates¶
When working with dates, most of the times it might be useful to add or subtract values of a given date, whether that is days, week, business days, or months, or even years. The delta methods offers a variety of functionalities that allow us to do just that.
The only argument that we need to worry about here is the integer value passed to the method depending on the delta case we are working with. Let's understand these methods in practice.
Adding or Subtracting Days¶
To add or subtract days from a given date, we can use the days_delta method.
Date(2024, 9, 23).days_delta(5)
Date(2024, 9, 28)
Date(2024, 9, 23).days_delta(-5)
Date(2024, 9, 18)
Adding or Subtracting Business Days¶
Fairly similar to the previous method, but in this case we have the option of specifying a calendar for the business days.
Date(2024, 9, 23).bizdays_delta(5, calendar='ANBIMA')
Date(2024, 9, 30)
Date(2024, 9, 23).bizdays_delta(-5, calendar='ANBIMA')
Date(2024, 9, 16)
Adding or Subtracting Weeks¶
By using the weeks_delta method we are able to add or subtract weeks from a given date.
Date(2024, 9, 23).weeks_delta(2)
Date(2024, 10, 7)
Date(2024, 9, 23).weeks_delta(-2)
Date(2024, 9, 9)
Adding or Subtracting Months¶
The months_delta method allows us to add or subtract months from a given date.
Date(2024, 9, 23).months_delta(2)
Date(2024, 11, 23)
Date(2024, 9, 23).months_delta(-2)
Date(2024, 7, 23)
Adding or Subtracting Years¶
Lastly, we have the years_delta method which is used to add or subtract years from a given date.
Date(2024, 9, 23).years_delta(2)
Date(2026, 9, 23)
Date(2024, 9, 23).years_delta(-2)
Date(2022, 9, 23)
Note: If you consider yourself a more generalist person you can simply use the delta method which encapsulates all functionality of the other delta methods.
It accepts a period integer which refers to the value that will be added or subtracted, and a periodicity string that could be either D for days, B for business days, W for weeks, M for months, or Y for years.
Here's how we can add 3 years and 2 weeks to our current date:
Working with Difference Between Dates¶
Besides adding or subtracting dates, we can also work with differences between dates, meaning that we are able to take two dates and return the difference between them in terms of days, weeks, months, or years.
All diff class methods accept a start_date and an end_date as arguments and return the difference as an integer.
Days Difference¶
Having at our disposal two dates, we can calculate the difference between those two dates in terms of days by using the days_diff method.
Business Days Difference¶
There is also the option of calculating the difference in business days between two dates. In this method we can optionally provide a calendar string for our weekends or holidays references.
start_date = Date(2024, 9, 23)
end_date = Date(2024, 9, 30)
Date.bizdays_diff(start_date, end_date, calendar='ANBIMA')
5
Weeks Difference¶
The weeks_diff method is used to calculate the difference between two dates in terms of weeks.
Months Difference¶
The months_diff method is used to calculate the difference between two dates in terms of months.
start_date = Date(2024, 9, 23)
end_date = Date(2024, 11, 23)
Date.months_diff(start_date, end_date)
2
Years Difference¶
In conclusion we have our years_diff method which as the name suggests, calculates the difference between two dates in terms of years.
A More General Approach¶
As mentioned before, the diff method encapsulates all the functionality of the other diff methods. It accepts a start_date and an end_date as arguments, and a periodicity string that could be either D for days, B for business days, W for weeks, M for months, or Y for years.
Let's see an example of how we can calculate the difference between two dates in terms of months and weeks using the diff method:
start_date = Date(2024, 9, 23)
end_date = Date(2024, 11, 23)
Date.diff(start_date, end_date, 'M')
2
start_date = Date(2024, 9, 23)
end_date = Date(2024, 10, 7)
Date.diff(start_date, end_date, 'W')
2
Working With Date Ranges¶
The range methods allows the user to generate lists filled with date objects based on a start_date and an end_date.
Create Days Range¶
Here is the implementation example of the days_range method which generates a range between two dates:
start_date = Date(2024, 9, 23)
end_date = Date(2024, 10, 1)
Date.days_range(start_date, end_date)
[
Date(2024, 9, 23),
Date(2024, 9, 24),
Date(2024, 9, 25),
Date(2024, 9, 26),
Date(2024, 9, 27),
Date(2024, 9, 28),
Date(2024, 9, 29),
Date(2024, 9, 30),
]
It is important to mention that the end_date value is exclusive, meaning it will not be included in the list.
Business Days Range¶
For the most part we will be working with Business Days, the section below demonstrates how to implement the bizdays_range.
start_date = Date(2024, 9, 23)
end_date = Date(2024, 10, 1)
Date.bizdays_range(start_date, end_date)
[
Date(2024, 9, 23),
Date(2024, 9, 24),
Date(2024, 9, 25),
Date(2024, 9, 26),
Date(2024, 9, 27),
Date(2024, 9, 30),
]
The bizdays_range method can also accept a calendar string for defining holidays.
Date.bizdays_range(start_date, end_date, calendar='ANBIMA')
[
Date(2024, 9, 23),
Date(2024, 9, 24),
Date(2024, 9, 25),
Date(2024, 9, 26),
Date(2024, 9, 27),
Date(2024, 9, 30),
]
Once again, if you consider yourself a more generalist person you can simply use the range method and specify the periodicity to be either B for business days or D for normal days which encapsulates all functionality of the other range methods.
start_date = Date(2024, 9, 23)
end_date = Date(2024, 9, 30)
Date.range(start_date, end_date, 'B')
[
Date(2024, 9, 23),
Date(2024, 9, 24),
Date(2024, 9, 25),
Date(2024, 9, 26),
Date(2024, 9, 27)
]
In the example above we used the character B, for extracting all the business days in that time period. Now let's use the character D for extracting normal days:
Date.range(start_date, end_date, 'D')
[
Date(2024, 9, 23),
Date(2024, 9, 24),
Date(2024, 9, 25),
Date(2024, 9, 26),
Date(2024, 9, 27),
Date(2024, 9, 28),
Date(2024, 9, 29)
]
Working with Expressions to extract Dates¶
The main and only method which we will need in order to extract the dates is the get_date_from_expression() method. The method accepts an expression string, a year, a month, and optionally a day and calendar as both integer and string respectively.
Extract a Business Day¶
Let's say that we wish to retrieve the tenth business day of October in the year 2024, here is how we can achieve this using the method mentioned above:
As you can see, the tenth business day of October falls in the 14th of the same month.
Let's breakdown the example above. Our first argument is a string containing the day in ordinal format followed by the type of the day, in this case a business day in the short form: bizday. Right after we simply specify the year and month.
Extract a Normal Day¶
In contrast to business days we have normal days, which will always take into account weekends and holidays. To retrieve normal dates we can run the following code:
The only difference from the previous example is the change of keywords, in the first example we used bizday in order to extract business day, now we are using day in order to extract normal days.
Keep this difference in mind because it will follow the same pattern throughout our entire module.
Intuitively, the method can also accept the keywords first, second, and third to extract the date.
Using the Calendar argument¶
Most of the times when working with dates we will also be using a specific calendar as our leading reference for the dates.
Let's highlight the main importance when it comes to using a specific calendar and take a look on how it can affect the output of our date. As a starting point, we will be retrieving the 15th business day of November in the year 2024.
Now watch what happens to our date when we set the calendar argument to the the ANBIMA calendar:
As seen above, the date got moved 4 days.
In our first example the business day pointed to the 21st day of the month, but in the second example, since we are specifying a calendar and by consequence adding holidays to the month, our business day will fall on the 25th.
Extract the Previous Business Day¶
The method also allows a more informal way of extracting dates by taking advantage of the previous keyword:
Date.get_date_from_expression('previous bizday', 2024, 11, 21, calendar='ANBIMA')
Date(2024, 11, 19)
Besides the expression, the only difference now is that we need to provide the day argument as a way to retrieve the previous business day.
Extract the Next Business Day¶
In contrast, we are also able to extract the next business day:
Note: we can also use the keyword day with the purpose of getting the previous or next normal day, but most of the times we will be working with business days.
Extract Business Day Based on the position¶
The method also allows the extraction of business days taking into consideration a position such as before or after, an ordinal day, let's understand this in practice:
Date.get_date_from_expression('first bizday after 15th day', 2024, 11, calendar='ANBIMA')
Date(2024, 11, 18)
Basically, this expression tells us the following: "Give me the first business day after the 15th day of the month".
We start by specifying whether we want the first, second, or third business day (bizday), then we tell the position which can be after or before, then in the end we specify the day, in this case 15th day.
Let's take a look at another example where we might want to extract the second bizday, this time before a specific date:
Date.get_date_from_expression('second bizday before 22nd day', 2024, 11, calendar='ANBIMA')
Date(2024, 11, 19)
Combining all the expressions¶
Now we arrive at a more complex way to extract the dates by combining the use of weekdays and all the already mentioned expressions.
Extract a Business Day After a specific day¶
Let's see how we can extract the first Wednesday after the 15th day of the month:
Date.get_date_from_expression('first wed bizday after 15th day', 2024, 11, calendar='ANBIMA')
Date(2024, 11, 27)
Now we have the introduction of weekdays, which are specified in their short format: mon, tue, wed, thu, fri, giving us a more practical room when it comes to extracting dates. Noticed that all the previous elements are still present in the expression, such as the bizday keyword, the day of the month in ordinal format, and the relative position including before or after.
Extract a Business Day Before a specific day¶
For instance, let's now extract the second Thursday, which is a business day, before the 15th day of September.