Skip to content

DOC/ENH: Holiday documentation is missing or hard to find for re-arranged national holidays.  #54382

Closed
@attack68

Description

@attack68
Contributor

Pandas version checks

  • I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#holidays-holiday-calendars

Documentation problem

I am creating a financial calendar using pandas holiday calendar functions: CustomBusinessDay and AbstractHolidayCalendar from a set of rules.

In UK the spring bank holiday is defined as the last Monday in May which we can code as a rule object:

Holiday("UK Spring Bank Holiday", month=5, day=31, offset=DateOffset(weekday=MO(-1)))

In 2022, to commemorate the Queen's Platinum Jubilee this holiday was moved to Thursday 2nd June and an extra holiday added on Friday 3rd June.

Adding an extra holiday to the rules is easy..

Holiday("Queen Jubilee Fri", year=2022, month=6, day=3)

I wondered if there were any options to the Holiday class that allowed excluding a list of dates from the observance. It was very difficult to find any documentation on the class and I had to resort to looking at the code.

In the code the class is poorly documented and has inaccuracies.

There was also no ability to do what I was hoping. The applied solution was:

rules = [
    Holiday("UK Spring Hol pre Jubilee", end_date=datetime(2022, 5, 1), month=5, day=31, offset=DateOffset(weekday=MO(-1))),
    Holiday("Queen Jubilee Thu", year=2022, month=6, day=2),
    Holiday("Queen Jubilee Fri", year=2022, month=6, day=3),
    Holiday("UK Spring Hol post Jubilee", start_date=datetime(2022, 7, 1), month=5, day=31, offset=DateOffset(weekday=MO(-1))),
]

### Suggested fix for documentation

.

Activity

added
Needs TriageIssue that has not been reviewed by a pandas team member
on Aug 3, 2023
removed
Needs TriageIssue that has not been reviewed by a pandas team member
on Jul 17, 2024
sharkipelago

sharkipelago commented on May 23, 2025

@sharkipelago
Contributor

take

sharkipelago

sharkipelago commented on May 23, 2025

@sharkipelago
Contributor

@mroeschke hi, just to confirm this issue is to add the functionality that @attack68 described- the ability to create a rule to exclude a holiday - and then to update the documentation with how to do an exclusion.

Or is this issue just to explicitly list in the documentation that it is not possible to do an exclusion and suggest the above workaround? Thanks.

attack68

attack68 commented on May 23, 2025

@attack68
ContributorAuthor

Personally I would have probably included an excludes or filter argument to remove certain dates from the Holiday generation

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

    Development

    Participants

    @mroeschke@attack68@sharkipelago

    Issue actions

      DOC/ENH: `Holiday` documentation is missing or hard to find for re-arranged national holidays. · Issue #54382 · pandas-dev/pandas