Julia library for handling holidays
using Holidays
country = "CA"
println(country_regions(country))
# --> ["AB", "BC", "MB", "NB", "NL", "NS", "NT", "NU", "ON", "PE", "QC", "SK", "YU"]
province = "MB"
dates = holiday_cache(country=country, region=province)
println(day_name(Date(2011, 1, 1), dates))
# --> "New Year's Day"
All currently available country codes and their correspondign lists of regions are listed below.
Country | Regions:
"CA" | ["AB", "BC", "MB", "NB", "NL", "NS", "NT", "NU", "ON", "PE", "QC", "SK", "YU"]
"US" | ["AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "GU",
"HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MH", "MA", "MI",
"FM", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND",
"MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT",
"VT", "VA", "VI", "WA", "WV", "WI", "WY"]
"MX" | [""]
"NZ" | ["NTL", "AUK", "TKI", "HKB", "WGN", "MBH", "NSN", "CAN", "STC", "WTL", "OTA", "STL", "CIT"]
"AU" | ["ACT", "NSW", "NT", "QLD", "SA", "TAS", "VIC", "WA"]
"AT" | ["B", "K", "N", "O", "S", "ST", "T", "V", "W"]
"DE" | ["BW", "BY", "BE", "BB", "HB", "HH", "HE", "MV", "NI", "NW", "RP", "SL", "SN", "ST", "SH", "TH"]
Presently, there are only a few functions exported by this module by default. country_regions, holiday_cache, and day_name
holiday_cache(; country::AbstractString="CA", region::AbstractString="MB", expand::Bool=true, observed::Bool=true, years::Array{Int}=Int[])
:
Populates holiday cache for the given years, country, and region. If observed is true, then
alternative observed dates will be set as well. If expand is true, then whenever a lookup
is made for a non cached date, that year of holidays will be populated in the cache.
Returns:
- `HolidayBase`: The cache for future calls to lookup dates.
-
day_name(date::Date, holidays::HolidayBase)
: Find corresponding holiday names for a date. If the given date is in the holiday cache this is a simple lookup. If it is not in cache, and expand is enabled, then the new year will be populated. Otherwise this will just return nothing.Returns:
AbstractString
: Holiday name for the given date, or Void if there is no corresponding holiday name.
-
country_regions(country::AbstractString)
: For lookup of regions in a countryReturns:
Array{AbstractString,N}
: Recognized regions within a given country
There is a build script for appveyor, but currently appveyor is disabled. PyCall in windows has some critical issues which makes the tests impossible to run.
If testing, you will need to install python, and pip install holidays
To run the default tests:
Pkg.test("Holidays")
This test has three configurable constants you may want to change.
regions: The keys of this dict are all country codes to test against. The corresponding Array is a list of province codes to test with this country.
const regions = Dict(
"CA"=>["AB", "BC", "MB", "NB", "NL", "NS", "NT", "NU", "ON", "PE", "QC", "SK", "YU"],
"US"=>["AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MH", "MA", "MI", "FM", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "VI", "WA", "WV", "WI", "WY"],
"MX"=>[""],
"NZ"=>["NTL", "AUK", "TKI", "HKB", "WGN", "MBH", "NSN", "CAN", "STC", "WTL", "OTA", "STL", "CIT"],
"AU" => ["ACT", "NSW", "NT", "QLD", "SA", "TAS", "VIC", "WA"],
"AT" => ["B", "K", "N", "O", "S", "ST", "T", "V", "W"],
"DE" => ["BW", "BY", "BE", "BB", "HB", "HH", "HE", "MV", "NI", "NW", "RP", "SL", "SN", "ST", "SH", "TH"],
)
start and end date:
# Set first and last date in loop
start_date = Date(1970, 1, 1)
last_date = Date(2030, 1, 1)
When tests are run, the program will loop through every region of every country. In each of these regions, it will loop all days from start_date to end_date and verify that this program has output matching holidays.py. Extensive testing (Over several centuries) can be rather slow, so configure the parameters according to what regions and times you need to verify succeed.
This script is useful for checking if this library is performing well in the version of julia installed.
julia benchmark.jl
This program loops from start_date to end_date querying the name of every date on the way. With a relatively light load:
start_date = Date(2010, 1, 1)
last_date = Date(2020, 1, 1)
Julia should be about 64 times faster than python, after it has been run once.
Python: 16.329613 seconds (9.10 M allocations: 212.836 MB, 0.74% gc time)
Julia : 0.264640 seconds (1.53 M allocations: 25.844 MB, 3.74% gc time)