Utility Functions

ofxtools.utils provides several utility functions and classes useful for working with financial data, particularly for investment account processing.

Securities Identifier Utilities

ofxtools can validate and convert between the three most common securities identifier formats: CUSIP (US), SEDOL (UK), and ISIN (international).

from ofxtools.utils import cusip2isin, sedol2isin, validate_cusip, validate_isin

# Validate a CUSIP
validate_cusip('084670207')   # True
validate_cusip('084670208')   # False (bad check digit)

# Convert CUSIP to ISIN (defaults to US country code)
cusip2isin('084670108')       # 'US0846701086'
cusip2isin('084670108', nation='CA')  # Canadian ISIN

# Convert SEDOL to ISIN (defaults to GB country code)
sedol2isin('0111009')         # 'GB0001110096'

# Validate an ISIN
validate_isin('US0846701086')  # True

NYSE Holiday Calendar

NYSEcalendar provides the official NYSE holiday schedule for a given year. The NYSE is closed on New Year’s Day, Martin Luther King Jr. Day, Washington’s Birthday, Good Friday, Memorial Day, Independence Day, Labor Day, Thanksgiving, and Christmas.

Weekend-shifted holidays follow NYSE convention: Saturday holidays are observed on the preceding Friday, Sunday holidays on the following Monday — except New Year’s Day falling on Saturday, which is simply skipped (December 31 is the year-end accounting close).

import datetime
from ofxtools.utils import NYSEcalendar

# Get all NYSE holidays for a year
NYSEcalendar.holidays(2024)
# [datetime.date(2024, 1, 1),   # New Year's Day (Monday)
#  datetime.date(2024, 1, 15),  # MLK Day
#  datetime.date(2024, 2, 19),  # Washington's Birthday
#  datetime.date(2024, 3, 29),  # Good Friday
#  datetime.date(2024, 5, 27),  # Memorial Day
#  datetime.date(2024, 7, 4),   # Independence Day (Thursday)
#  datetime.date(2024, 9, 2),   # Labor Day
#  datetime.date(2024, 11, 28), # Thanksgiving (4th Thursday)
#  datetime.date(2024, 12, 25)] # Christmas (Wednesday)

# Get all Mondays in a given month (useful for computing floating holidays)
NYSEcalendar.mondays(2024, 1)
# [datetime.date(2024, 1, 1), datetime.date(2024, 1, 8), ...]

# Get all Thursdays in November (for Thanksgiving)
NYSEcalendar.thursdays(2024, 11)
# [datetime.date(2024, 11, 7), ..., datetime.date(2024, 11, 28)]

findEaster computes Easter Sunday for any Gregorian calendar year (valid 1583–4099), which is needed to derive Good Friday:

from ofxtools.utils import findEaster

findEaster(2024)  # datetime.date(2024, 3, 31)
findEaster(2025)  # datetime.date(2025, 4, 20)

Settlement Date Utilities

US equity settlement moved to T+1 (trade date plus one business day) in May 2024. Most bonds and many international markets still settle T+2. settleDate and nextBizDay handle both, skipping weekends and NYSE holidays.

import datetime
from ofxtools.utils import nextBizDay, settleDate

trade_date = datetime.date(2024, 3, 28)  # Thursday before Good Friday

# Next NYSE business day (skips Good Friday 3/29 and weekend)
nextBizDay(trade_date)   # datetime.date(2024, 4, 1)

# T+1 settlement (US equity default since May 2024)
settleDate(trade_date)          # datetime.date(2024, 4, 1)

# T+2 settlement (bonds, some international markets)
settleDate(trade_date, n=2)     # datetime.date(2024, 4, 2)

# Friday trade: T+1 settles Monday (skips weekend)
settleDate(datetime.date(2024, 6, 7))  # datetime.date(2024, 6, 10)