Skip to content

examples.rst

Latest commit

 

History

History
265 lines (198 loc) · 7.86 KB

examples.rst

File metadata and controls

265 lines (198 loc) · 7.86 KB
Raw

Additional Examples

Simplest example possible

>>> from datetime import date
>>> import holidays
>>> date(2014, 1, 1) in holidays.US()
True
>>> date(2014, 1, 2) in holidays.US()
False

Tip

Don't do this! It is not efficient because it is initializing a new Holiday object and generating a list of all the holidays in 2014 during each comparison.

It is more efficient to create the object only once:

>>> us_holidays = holidays.US()
>>> date(2014, 1, 1) in us_holidays
True
>>> date(2014, 1, 2) in us_holidays
False

You can use the :py:func:`country_holidays` function to create the object using a string with the country code:

>>> us_holidays = holidays.country_holidays('US')

Let's print out the holidays in 2014 specific to California, USA:

>>> for date, name in sorted(holidays.US(state='CA', years=2014).items()):
>>>     print(date, name)
2014-01-01 New Year's Day
2014-01-20 Martin Luther King Jr. Day
2014-02-15 Susan B. Anthony Day
2014-02-17 Washington's Birthday
2014-03-31 César Chávez Day
2014-05-26 Memorial Day
2014-07-04 Independence Day
2014-09-01 Labor Day
2014-10-13 Columbus Day
2014-11-11 Veterans Day
2014-11-27 Thanksgiving
2014-12-25 Christmas Day

So far we've only checked holidays in 2014 so that's the only year the Holidays object has generated:

>>> us_holidays.years
set([2014])
>>> len(us_holidays)
10

Expand parameter

Because by default the :py:attr:`expand` parameter is True the Holiday object will calculate and add holidays for other years when they are required:

>>> date(2013, 1, 1) in us_holidays
True
>>> us_holidays.years
set([2013, 2014])
>>> len(us_holidays)
20

If we change the :py:attr:`expand` parameter to False the Holiday object will no longer add holidays from new years:

>>> us_holidays.expand = False
>>> date(2012, 1, 1) in us_holidays
False
>>> us.holidays.expand = True
>>> date(2012, 1, 1) in us_holidays
True

Observed parameter

January 1st, 2012 fell on a Sunday so the statutory holiday was observed on the 2nd. By default the :py:attr:`observed` param is True so the holiday list will include January 2nd, 2012 as a holiday:

>>> date(2012, 1, 1) in us_holidays
True
>>> us_holidays[date(2012, 1, 1)]
"New Year's Day"
>>> date(2012, 1, 2) in us_holidays
True
>>> us_holidays.get(date(2012 ,1, 2))
"New Year's Day (Observed)"

The values of :py:attr:`observed` and :py:attr:`expand` can be changed on the fly and the holiday list will be adjusted accordingly:

>>> us_holidays.observed = False
>>> date(2012, 1, 2) in us_holidays
False
us_holidays.observed = True
>> date(2012, 1, 2) in us_holidays
True

Date from holiday name

Holidays can be retrieved using their name too. :py:meth:`get_named` receives a string and returns a list of holidays matching it (even partially, with case insensitive check):

>>> us_holidays = holidays.UnitedStates(years=2020)
>>> us_holidays.get_named('day')
[datetime.date(2020, 1, 1), datetime.date(2020, 1, 20),
datetime.date(2020, 2, 17), datetime.date(2020, 5, 25),
datetime.date(2020, 7, 4), datetime.date(2020, 7, 3),
datetime.date(2020, 9, 7), datetime.date(2020, 10, 12),
datetime.date(2020, 11, 11), datetime.date(2020, 12, 25)]

Additions

Holiday objects can be added together and the resulting object will generate the holidays from all of the initial objects:

>>> north_america = holidays.CA() + holidays.US() + holidays.MX()
>>> north_america.get('2014-07-01')
"Canada Day"
>>> north_america.get('2014-07-04')
"Independence Day"

The other form of addition is also available:

>>> north_america = holidays.CA()
>>> north_america += holidays.US()
>>> north_america += holidays.MX()
>>> north_america.country
['CA', 'US', 'MX']

We can even get a set of holidays that include all the province- or state-specific holidays using the built-in :py:func:`sum` function:

>>> a = sum([holidays.CA(prov=x) for x in holidays.CA.PROVINCES])
>>> a.prov
PROVINCES = ['AB', 'BC', 'MB', 'NB', 'NL', 'NS', 'NT', 'NU', 'ON', 'PE',
             'QC', 'SK', 'YU']

Creating custom holidays (or augmenting existing ones with private ones)

Sometimes we may not be able to use the official federal statutory holiday list in our code. Let's pretend we work for a company that does not include Columbus Day as a statutory holiday but does include "Ninja Turtle Day" on July 13th. We can create a new class that inherits the US and the only method we need to override is :py:meth:`_populate`:

>>> class CorporateHolidays(holidays.US):
>>>     def _populate(self, year):
>>>         # Populate the holiday list with the default US holidays
>>>         holidays.US._populate(self, year)
>>>         # Remove Columbus Day
>>>         self.pop_named("Columbus Day")
>>>         # Add Ninja Turtle Day
>>>         self[date(year, 7, 13)] = "Ninja Turtle Day"
>>> date(2014, 10, 14) in Holidays(country="US")
True
>>> date(2014, 10, 14) in CorporateHolidays(country="US")
False
>>> date(2014, 7, 13) in Holidays(country="US")
False
>>> date(2014 ,7, 13) in CorporateHolidays(country="US")
True

We can also inherit from the HolidayBase class which has an empty :py:meth:`_populate` method so we start with no holidays and must define them all ourselves. This is how we would create a holidays class for a country that is not supported yet:

>>> class NewCountryHolidays(holidays.HolidayBase):
>>>     def _populate(self, year):
>>>         self[date(year, 1, 2)] = "Some Federal Holiday"
>>>         self[date(year, 2, 3)] = "Another Federal Holiday"
>>> hdays = NewCountryHolidays()

We can also include prov/state specific holidays in our new class:

>>> class NewCountryHolidays(holidays.HolidayBase):
>>>     def _populate(self, year):
>>>         # Set default prov if not provided
>>>         if self.prov == None:
>>>             self.prov = 'XX'
>>>         self[date(year, 1, 2)] = "Some Federal Holiday"
>>>         if self.prov == 'XX':
>>>             self[date(year, 2, 3)] = "Special XX province-only holiday"
>>>         if self.prov == 'YY':
>>>             self[date(year, 3, 4)] = "Special YY province-only holiday"
>>> hdays = NewCountryHolidays()
>>> hdays = NewCountryHolidays(prov='XX')

If you write the code necessary to create a holiday class for a country not currently supported please contribute your code to the project!

Perhaps you just have a list of dates that are holidays and want to turn them into a Holiday class to access all the useful functionality. You can use the py:meth:append() method which accepts a dictionary of {date: name} pairs, a list of dates, or even singular date/string/timestamp objects:

>>> custom_holidays = holidays.HolidayBase()
>>> custom_holidays.append(['2015-01-01', '07/04/2015'])
>>> custom_holidays.append(date(2015, 12, 25))

Other ways to specify the country

Each country has two class names that can be called in addition to the alpha-2 ISO code: its 3-digit ISO code and an internal class name.

>>> holidays.USA() == holidays.US()
True
>>> holidays.UnitedStates() == holidays.US()
True
.. deprecated:: In the future