QuantLib python ql.schedule getting end of month dates

I'd like to add some color to David Duarte's excellent answer.

When a corporate or emerging markets bond originates, some junior person is tasked with making up the list of coupon dates for the prospectus. These days they usually use a tool that undersands commonly used conventions, but decades ago they did it manually and sometimes messed up. I used to check to make sure that my library (not ql, but a similar scheduler, a little more flexible) matched the dates in the prospectus, and ended up writing a few lines of C++ code that took as input the dates from the prospectus and the parameters on Bloomberg terminal (if available) and tried different combinations of the scheduler parameters trying to match the dates. Sometimes we encountered a bond where this failed, so the schedule from the prospectus had to be a custom list of dates. Thid seldom happens now, was not needed for your bond, but operationally one should be prepared for this eventuality.

The code also indicated whether you need to specify firstDate for odd first period and penultimate (nextToLastDate) for odd last period. In my opinion, it is better practice not to pass them if they are redundant - only pass them if they make a difference. Many bonds have odd first and/or last periods. (Very few bonds have odd periods in the middle of the schedule.)

You may want to write a tool like this for QL schedule and contribute it to the community.

Please keep in mind that there is no such thing as "USD Holiday". While for many other currencies, there is one calendar that everyone uses, so one can call the London calendar "GBP Calendar", this just doesn't work for US. There are different holidays used in the US for stocks (NYSE) and bonds and a few others too. Using ql.UnitedStates() without specifying which calendar you mean (e.g. GovernmentBond) can lead to confusion. Take a look at https://www.sifma.org/resources/general/holiday-schedule/ and scroll down to "U.S. Holiday Recommendations". Click on 2021, observe that it says "Early Close (2:00 p.m. Eastern Time): Friday, December 31, 2021".

Let's try your problematic date in QL:

NewYearsEve = ql.Date(31,12,2021) # Because New Years day, January 1st, 2022 is a Saturday, some holiday calendars have an observed holiday here

ql.UnitedStates().isBusinessDay(NewYearsEve) # Bad!

ql.UnitedStates(ql.UnitedStates.Settlement).isBusinessDay(NewYearsEve)

ql.UnitedStates(ql.UnitedStates.LiborImpact).isBusinessDay(NewYearsEve)

are False, but

ql.UnitedStates(ql.UnitedStates.NYSE).isBusinessDay(NewYearsEve)

ql.UnitedStates(ql.UnitedStates.GovernmentBond).isBusinessDay(NewYearsEve)

ql.UnitedStates(ql.UnitedStates.NERC).isBusinessDay(NewYearsEve)

ql.UnitedStates(ql.UnitedStates.FederalReserve).isBusinessDay(NewYearsEve)

are True. I see no reason not to have a bond coupon on this date.

An example of stocks and bonds using different calendars

IndigenousPeoplesDay = ql.Date(11,10,2021) # aka Canadian Thanksgiving, Columbus Day

ql.UnitedStates().isBusinessDay(IndigenousPeoplesDay) # Bad!

ql.UnitedStates(ql.UnitedStates.Settlement).isBusinessDay(IndigenousPeoplesDay) )

ql.UnitedStates(ql.UnitedStates.GovernmentBond).isBusinessDay(IndigenousPeoplesDay)

are False, but

ql.UnitedStates(ql.UnitedStates.NYSE).isBusinessDay(IndigenousPeoplesDay)

is True - you can trade stocks.

CDR function on Bloomberg Terminal is a great place to expore holiday calendars if you're curious.

The constructor for a Schedule in QuantLib is:

ql.Schedule(effectiveDate, terminationDate, tenor,
            calendar, convention, terminationDateConvention, rule,
            endOfMonth, firstDate=Date(), nextToLastDate=Date()
)

The way you have it defined, you are basically rolling on the 30th and that's why you have a difference in those 4 dates:

mydates =  [
'2020-04-01', 
'2020-06-30', '2020-09-30', '2020-12-31', '2021-03-31', '2021-06-30',
'2021-09-30', '2021-12-31', '2022-03-31', '2022-06-30', '2022-09-30',    
]

schedule = ql.Schedule(
ql.Date('01-04-2020', '%d-%m-%Y'),
ql.Date('30-09-2022', '%d-%m-%Y'),
ql.Period("3m"),
ql.UnitedStates(),
ql.ModifiedFollowing,
ql.ModifiedFollowing,
ql.DateGeneration.Forward,
False,
ql.Date('30-06-2020', '%d-%m-%Y'))

pd.DataFrame({
    "mydates": mydates,
    "qlDates": [dt.ISO() for dt in schedule]
}).style.apply(lambda row: ["background: red; color: white"]*2  if row[0] != row[1] else [""]*2, axis = 1)

Also, notice that one of the dates in your list is not a business day in the ql.UnitedStated calendar so you can't generate those dates with an adjusted business day convention:

cal = ql.UnitedStates()
[cal.isBusinessDay(ql.Date(dt, '%Y-%m-%d')) for dt in mydates]

[True, True, True, True, True, True, True, False, True, True, True]

So my sugestion would be:

• Change the conventions to Unadjusted since you want a date that is not a business day
• Change the endOfMonth to True
• Change the date generation rule to Backward
• Loose the firstDate parameter as you don't have any stub (and you were actually setting the roll date to the 30th with this)

schedule = ql.Schedule(
ql.Date('01-04-2020', '%d-%m-%Y'),
ql.Date('30-09-2022', '%d-%m-%Y'),
ql.Period("3m"),
ql.UnitedStates(),
ql.Unadjusted,
ql.Unadjusted,
ql.DateGeneration.Backward,
True)

pd.DataFrame({
    "mydates": mydates,
    "qlDates": [dt.ISO() for dt in schedule]
}).style.apply(lambda row: ["background: red"]*2  if row[0] != row[1] else [""]*2, axis = 1)

Edit after comments: As Dimitri very well pointed out there is no single "USD Holiday" calendar and what you have are several combinations of US holidays used by different markets/asset classes/exchanges.

In QuantLib, you can specify some of these. For example, that date in question (31-12-2021) will be treated diferently throughout the alternatives:

mydate = ql.Date(31,12,2021)
cal = ql.UnitedStates()
alts = ['FederalReserve', 'GovernmentBond', 'LiborImpact', 'NERC', 'NYSE', 'Settlement']
for alt in alts:
    mycalendar = eval(f'ql.UnitedStates(ql.UnitedStates.{alt})')
    print(alt, mycalendar.isBusinessDay(mydate))

FederalReserve True
GovernmentBond True
LiborImpact False
NERC True
NYSE True
Settlement False

Also a great point about "junior generated" schedules and I've seen it a few times. Some schedules, and it can be for bonds or derivatives, simply can't be generated by market convention rules, and in extreme cases you might just have to insert them manually. In QuantLib, you can do it like so:

schedule = ql.Schedule([ql.Date(dt, '%Y-%m-%d') for dt in mydates])
print([*schedule])