Skip to content

date_formulas

shortfx.fxExcel.date_formulas

Excel-style date functions.

This module provides Excel-compatible date and time functions for Python. All functions follow Excel's naming conventions and behaviors, including Excel's serial number date system (days since December 30, 1899).

Functions

DATE(year: int, month: int, day: int) -> float

Returns the Excel serial number corresponding to a particular date. Excel/Spanish name: FECHA

Description: Converts a given year, month, and day into an Excel serial number. The serial number is the number of days since December 30, 1899.

Args: year: The year (1900-9999). month: The month (1-12). day: The day of the month (1-31).

Returns: float: The Excel serial number representing the date.

Raises: ValueError: If the date values are invalid.

Usage Example: >>> DATE(2025, 1, 15) 45667.0 >>> DATE(2024, 12, 31) 45657.0

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
def DATE(year: int, month: int, day: int) -> float:
    """
    Returns the Excel serial number corresponding to a particular date.
    Excel/Spanish name: FECHA

    **Description:**
    Converts a given year, month, and day into an Excel serial number.
    The serial number is the number of days since December 30, 1899.

    **Args:**
        year: The year (1900-9999).
        month: The month (1-12).
        day: The day of the month (1-31).

    **Returns:**
        float: The Excel serial number representing the date.

    **Raises:**
        ValueError: If the date values are invalid.

    **Usage Example:**
        >>> DATE(2025, 1, 15)
        45667.0
        >>> DATE(2024, 12, 31)
        45657.0

    **Cost:** O(1)
    """
    return _int_date_to_excel_serial(year, month, day)

DATEDIF(start_date: datetime, end_date: datetime, unit: str) -> int

Calculates the difference between dates in various units.

Description

Equivalent to Excel's DATEDIF function. Calculates the difference between two dates in complete years, months, days, or partial combinations.

Parameters:

Name Type Description Default
start_date datetime

The start date.

 required
end_date datetime

The end date.

 required
unit str

Unit to return: - 'Y' — complete years between the dates. - 'M' — complete months between the dates. - 'D' — total days between the dates. - 'MD' — days difference ignoring months and years. - 'YM' — months difference ignoring years. - 'YD' — days difference ignoring years.

 required

Returns:

Name Type Description
int int

The difference in the specified unit.
Usage Example

from datetime import datetime from shortfx.fxExcel.date_formulas import DATEDIF start = datetime(2020, 1, 15) end = datetime(2025, 3, 20) DATEDIF(start, end, "Y") 5 DATEDIF(start, end, "MD") 5 DATEDIF(start, end, "YM") 2 DATEDIF(start, end, "YD") 64

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
def DATEDIF(start_date: datetime, end_date: datetime, unit: str) -> int:
    """Calculates the difference between dates in various units.

    Description:
        Equivalent to Excel's DATEDIF function. Calculates the difference between
        two dates in complete years, months, days, or partial combinations.

    Args:
        start_date (datetime): The start date.
        end_date (datetime): The end date.
        unit (str): Unit to return:
            - ``'Y'``  — complete years between the dates.
            - ``'M'``  — complete months between the dates.
            - ``'D'``  — total days between the dates.
            - ``'MD'`` — days difference ignoring months and years.
            - ``'YM'`` — months difference ignoring years.
            - ``'YD'`` — days difference ignoring years.

    Returns:
        int: The difference in the specified unit.

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxExcel.date_formulas import DATEDIF
        >>> start = datetime(2020, 1, 15)
        >>> end = datetime(2025, 3, 20)
        >>> DATEDIF(start, end, "Y")
        5
        >>> DATEDIF(start, end, "MD")
        5
        >>> DATEDIF(start, end, "YM")
        2
        >>> DATEDIF(start, end, "YD")
        64

    Cost: O(1)
    """
    return _core_datedif(start_date, end_date, unit)

DATEVALUE(date_text: str) -> float

Converts a date in text format to an Excel serial number. Excel/Spanish name: FECHANUMERO

Description: Converts a text representation of a date into an Excel serial number. Accepts dates in DD/MM/YYYY format.

Args: date_text: A date string in DD/MM/YYYY format.

Returns: float: The Excel serial number representing the date.

Raises: ValueError: If the date format is invalid.

Usage Example: >>> DATEVALUE("15/01/2025") 45667.0 >>> DATEVALUE("31/12/2024") 45657.0

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
def DATEVALUE(date_text: str) -> float:
    """
    Converts a date in text format to an Excel serial number.
    Excel/Spanish name: FECHANUMERO

    **Description:**
    Converts a text representation of a date into an Excel serial number.
    Accepts dates in DD/MM/YYYY format.

    **Args:**
        date_text: A date string in DD/MM/YYYY format.

    **Returns:**
        float: The Excel serial number representing the date.

    **Raises:**
        ValueError: If the date format is invalid.

    **Usage Example:**
        >>> DATEVALUE("15/01/2025")
        45667.0
        >>> DATEVALUE("31/12/2024")
        45657.0

    **Cost:** O(1)
    """
    return _date_to_excel_serial(date_text)

DAY(serial_number: Union[float, datetime]) -> int

Converts an Excel serial number to a day of the month. Excel/Spanish name: DAY (DIA in Spanish contexts)

Description: Extracts the day component (1-31) from an Excel serial number or datetime object.

Args: serial_number: An Excel serial number or datetime object.

Returns: int: The day of the month (1-31).

Raises: ValueError: If the serial number is invalid.

Usage Example: >>> from datetime import datetime >>> DAY(45667.0) # January 15, 2025 15 >>> DAY(datetime(2025, 1, 15)) 15

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
def DAY(serial_number: Union[float, datetime]) -> int:
    """
    Converts an Excel serial number to a day of the month.
    Excel/Spanish name: DAY (DIA in Spanish contexts)

    **Description:**
    Extracts the day component (1-31) from an Excel serial number or datetime object.

    **Args:**
        serial_number: An Excel serial number or datetime object.

    **Returns:**
        int: The day of the month (1-31).

    **Raises:**
        ValueError: If the serial number is invalid.

    **Usage Example:**
        >>> from datetime import datetime
        >>> DAY(45667.0)  # January 15, 2025
        15
        >>> DAY(datetime(2025, 1, 15))
        15

    **Cost:** O(1)
    """
    return _excel_serial_to_day(serial_number)

DAYS(end_date: datetime, start_date: datetime) -> int

Returns the number of days between two dates.

Description

Calculates the difference in days between two dates. This is equivalent to Excel's DAYS function. The result can be negative if end_date is before start_date.

Parameters:

Name Type Description Default
end_date datetime

The end date.

 required
start_date datetime

The start date.

 required

Returns:

Name Type Description
int int

The number of days between the dates (can be negative).
Usage Example

from datetime import datetime from shortfx.fxExcel.date_formulas import DAYS start = datetime(2025, 1, 1) end = datetime(2025, 1, 15) DAYS(end, start) 14 DAYS(start, end) -14

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def DAYS(end_date: datetime, start_date: datetime) -> int:
    """Returns the number of days between two dates.

    Description:
        Calculates the difference in days between two dates. This is equivalent
        to Excel's DAYS function. The result can be negative if end_date is
        before start_date.

    Args:
        end_date (datetime): The end date.
        start_date (datetime): The start date.

    Returns:
        int: The number of days between the dates (can be negative).

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxExcel.date_formulas import DAYS
        >>> start = datetime(2025, 1, 1)
        >>> end = datetime(2025, 1, 15)
        >>> DAYS(end, start)
        14
        >>> DAYS(start, end)
        -14

    Cost: O(1)
    """
    return _core_days_between(start_date, end_date)

DAYS360(start_date: datetime, end_date: datetime, method: bool = False) -> int

Calculates days between two dates based on a 360-day year.

Description

Equivalent to Excel's DAYS360 function. This function calculates the number of days between two dates using a 360-day year (12 months of 30 days). This is commonly used in financial calculations.

Parameters:

Name Type Description Default
start_date datetime

The start date.

 required
end_date datetime

The end date.

 required
method bool

False for US method (NASD), True for European method. Defaults to False.

 False

Returns:

Name Type Description
int int

Number of days based on 360-day year calculation.
Usage Example

from datetime import datetime from shortfx.fxExcel.date_formulas import DAYS360 start = datetime(2025, 1, 30) end = datetime(2025, 2, 28) DAYS360(start, end) # US method 28 DAYS360(start, end, method=True) # European method 28

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def DAYS360(start_date: datetime, end_date: datetime, method: bool = False) -> int:
    """Calculates days between two dates based on a 360-day year.

    Description:
        Equivalent to Excel's DAYS360 function. This function calculates the
        number of days between two dates using a 360-day year (12 months of 30 days).
        This is commonly used in financial calculations.

    Args:
        start_date (datetime): The start date.
        end_date (datetime): The end date.
        method (bool, optional): False for US method (NASD), True for European method.
                                Defaults to False.

    Returns:
        int: Number of days based on 360-day year calculation.

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxExcel.date_formulas import DAYS360
        >>> start = datetime(2025, 1, 30)
        >>> end = datetime(2025, 2, 28)
        >>> DAYS360(start, end)  # US method
        28
        >>> DAYS360(start, end, method=True)  # European method
        28

    Cost: O(1)
    """
    return _core_days_360(start_date, end_date, method='eu' if method else 'us')

EDATE(start_date: Union[datetime, float], months: int) -> float

Returns the serial number of a date months before or after.

Description

Equivalent to Excel's EDATE function. Returns the Excel serial number representing a date that is the indicated number of months before or after the start date.

Parameters:

Name Type Description Default
start_date Union[datetime, float]

Starting date as datetime or Excel serial number.

 required
months int

Number of months to add (positive) or subtract (negative).

 required

Returns:

Name Type Description
float float

Excel serial number of the resulting date.
Usage Example

from datetime import datetime from shortfx.fxExcel.date_formulas import EDATE start = datetime(2025, 1, 31) EDATE(start, 1) # One month later (Feb 28, 2025) 45688.0 EDATE(start, -1) # One month earlier (Dec 31, 2024) 45627.0

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def EDATE(start_date: Union[datetime, float], months: int) -> float:
    """Returns the serial number of a date months before or after.

    Description:
        Equivalent to Excel's EDATE function. Returns the Excel serial number
        representing a date that is the indicated number of months before or
        after the start date.

    Args:
        start_date (Union[datetime, float]): Starting date as datetime or Excel serial number.
        months (int): Number of months to add (positive) or subtract (negative).

    Returns:
        float: Excel serial number of the resulting date.

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxExcel.date_formulas import EDATE
        >>> start = datetime(2025, 1, 31)
        >>> EDATE(start, 1)  # One month later (Feb 28, 2025)
        45688.0
        >>> EDATE(start, -1)  # One month earlier (Dec 31, 2024)
        45627.0

    Cost: O(1)
    """
    if isinstance(start_date, (int, float)):
        start_date = datetime(1899, 12, 30) + timedelta(days=start_date)

    result = _core_add_months(start_date, months)
    return _int_date_to_excel_serial(result.year, result.month, result.day)

EOMONTH(start_date: Union[datetime, float], months: int) -> float

Returns the serial number of the last day of the month.

Description

Equivalent to Excel's EOMONTH function. Returns the Excel serial number for the last day of the month that is the indicated number of months before or after start_date.

Parameters:

Name Type Description Default
start_date Union[datetime, float]

Starting date as datetime or Excel serial number.

 required
months int

Number of months to add (positive) or subtract (negative).

 required

Returns:

Name Type Description
float float

Excel serial number of the last day of the resulting month.
Usage Example

from datetime import datetime from shortfx.fxExcel.date_formulas import EOMONTH start = datetime(2025, 1, 15) EOMONTH(start, 0) # Last day of January 2025 45658.0 EOMONTH(start, 1) # Last day of February 2025 45686.0

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
def EOMONTH(start_date: Union[datetime, float], months: int) -> float:
    """Returns the serial number of the last day of the month.

    Description:
        Equivalent to Excel's EOMONTH function. Returns the Excel serial number
        for the last day of the month that is the indicated number of months
        before or after start_date.

    Args:
        start_date (Union[datetime, float]): Starting date as datetime or Excel serial number.
        months (int): Number of months to add (positive) or subtract (negative).

    Returns:
        float: Excel serial number of the last day of the resulting month.

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxExcel.date_formulas import EOMONTH
        >>> start = datetime(2025, 1, 15)
        >>> EOMONTH(start, 0)  # Last day of January 2025
        45658.0
        >>> EOMONTH(start, 1)  # Last day of February 2025
        45686.0

    Cost: O(1)
    """
    if isinstance(start_date, (int, float)):
        start_date = datetime(1899, 12, 30) + timedelta(days=start_date)

    result = _core_end_of_month_offset(start_date, months)

    return _int_date_to_excel_serial(result.year, result.month, result.day)

HOUR(serial_number: Union[float, datetime]) -> int

Converts an Excel serial number to an hour value. Excel/Spanish name: HOUR (HORA as function name in Spanish)

Description: Extracts the hour component (0-23) from an Excel serial number or datetime object.

Args: serial_number: An Excel serial number or datetime object.

Returns: int: The hour (0-23).

Raises: ValueError: If the serial number is invalid.

Usage Example: >>> HOUR(0.5) # 12:00 PM 12 >>> HOUR(0.75) # 6:00 PM 18

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
def HOUR(serial_number: Union[float, datetime]) -> int:
    """
    Converts an Excel serial number to an hour value.
    Excel/Spanish name: HOUR (HORA as function name in Spanish)

    **Description:**
    Extracts the hour component (0-23) from an Excel serial number or datetime object.

    **Args:**
        serial_number: An Excel serial number or datetime object.

    **Returns:**
        int: The hour (0-23).

    **Raises:**
        ValueError: If the serial number is invalid.

    **Usage Example:**
        >>> HOUR(0.5)  # 12:00 PM
        12
        >>> HOUR(0.75)  # 6:00 PM
        18

    **Cost:** O(1)
    """
    return _excel_serial_to_hour(serial_number)

ISOWEEKNUM(date: datetime) -> int

Returns the ISO week number.

Description

Equivalent to Excel's ISOWEEKNUM function. Returns the ISO week number of the year for a given date (1-53).

Parameters:

Name Type Description Default
date datetime

The date to evaluate.

 required

Returns:

Name Type Description
int int

ISO week number (1-53).
Usage Example

from datetime import datetime from shortfx.fxExcel.date_formulas import ISOWEEKNUM ISOWEEKNUM(datetime(2025, 1, 1)) 1 ISOWEEKNUM(datetime(2025, 6, 15)) 24

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
def ISOWEEKNUM(date: datetime) -> int:
    """Returns the ISO week number.

    Description:
        Equivalent to Excel's ISOWEEKNUM function. Returns the ISO week number
        of the year for a given date (1-53).

    Args:
        date (datetime): The date to evaluate.

    Returns:
        int: ISO week number (1-53).

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxExcel.date_formulas import ISOWEEKNUM
        >>> ISOWEEKNUM(datetime(2025, 1, 1))
        1
        >>> ISOWEEKNUM(datetime(2025, 6, 15))
        24

    Cost: O(1)
    """
    return _core_iso_week_number(date)

MINUTE(serial_number: Union[float, datetime]) -> int

Converts an Excel serial number to a minute value. Excel/Spanish name: MINUTE (MINUTO in Spanish)

Description: Extracts the minute component (0-59) from an Excel serial number or datetime object.

Args: serial_number: An Excel serial number or datetime object.

Returns: int: The minute (0-59).

Raises: ValueError: If the serial number is invalid.

Usage Example: >>> from datetime import datetime >>> MINUTE(datetime(2025, 1, 15, 14, 30)) 30 >>> MINUTE(0.604166667) # Approximately 2:30 PM 30

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
def MINUTE(serial_number: Union[float, datetime]) -> int:
    """
    Converts an Excel serial number to a minute value.
    Excel/Spanish name: MINUTE (MINUTO in Spanish)

    **Description:**
    Extracts the minute component (0-59) from an Excel serial number or datetime object.

    **Args:**
        serial_number: An Excel serial number or datetime object.

    **Returns:**
        int: The minute (0-59).

    **Raises:**
        ValueError: If the serial number is invalid.

    **Usage Example:**
        >>> from datetime import datetime
        >>> MINUTE(datetime(2025, 1, 15, 14, 30))
        30
        >>> MINUTE(0.604166667)  # Approximately 2:30 PM
        30

    **Cost:** O(1)
    """
    return _excel_serial_to_minute(serial_number)

MONTH(serial_number: Union[float, datetime]) -> int

Converts an Excel serial number to a month value. Excel/Spanish name: MONTH (MES in Spanish)

Description: Extracts the month component (1-12) from an Excel serial number or datetime object.

Args: serial_number: An Excel serial number or datetime object.

Returns: int: The month (1-12).

Raises: ValueError: If the serial number is invalid.

Usage Example: >>> from datetime import datetime >>> MONTH(45667.0) # January 15, 2025 1 >>> MONTH(datetime(2025, 6, 15)) 6

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
def MONTH(serial_number: Union[float, datetime]) -> int:
    """
    Converts an Excel serial number to a month value.
    Excel/Spanish name: MONTH (MES in Spanish)

    **Description:**
    Extracts the month component (1-12) from an Excel serial number or datetime object.

    **Args:**
        serial_number: An Excel serial number or datetime object.

    **Returns:**
        int: The month (1-12).

    **Raises:**
        ValueError: If the serial number is invalid.

    **Usage Example:**
        >>> from datetime import datetime
        >>> MONTH(45667.0)  # January 15, 2025
        1
        >>> MONTH(datetime(2025, 6, 15))
        6

    **Cost:** O(1)
    """
    return _excel_serial_to_month(serial_number)

NETWORKDAYS(start_date: datetime, end_date: datetime, holidays: Optional[List[datetime]] = None) -> int

Returns the number of working days between two dates.

Description

Equivalent to Excel's NETWORKDAYS function. Calculates the number of working days (Monday-Friday) between two dates, excluding weekends and optional holidays.

Parameters:

Name Type Description Default
start_date datetime

The start date.

 required
end_date datetime

The end date.

 required
holidays Optional[List[datetime]]

List of holiday dates to exclude. Defaults to None.

 None

Returns:

Name Type Description
int int

Number of working days.
Usage Example

from datetime import datetime from shortfx.fxExcel.date_formulas import NETWORKDAYS start = datetime(2025, 1, 6) # Monday end = datetime(2025, 1, 10) # Friday NETWORKDAYS(start, end) 5 holidays = [datetime(2025, 1, 8)] NETWORKDAYS(start, end, holidays) 4

Cost: O(n) where n is the number of days between dates

Source code in shortfx/fxExcel/date_formulas.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def NETWORKDAYS(start_date: datetime, end_date: datetime, holidays: Optional[List[datetime]] = None) -> int:
    """Returns the number of working days between two dates.

    Description:
        Equivalent to Excel's NETWORKDAYS function. Calculates the number of
        working days (Monday-Friday) between two dates, excluding weekends
        and optional holidays.

    Args:
        start_date (datetime): The start date.
        end_date (datetime): The end date.
        holidays (Optional[List[datetime]], optional): List of holiday dates to exclude.
                                                       Defaults to None.

    Returns:
        int: Number of working days.

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxExcel.date_formulas import NETWORKDAYS
        >>> start = datetime(2025, 1, 6)  # Monday
        >>> end = datetime(2025, 1, 10)   # Friday
        >>> NETWORKDAYS(start, end)
        5
        >>> holidays = [datetime(2025, 1, 8)]
        >>> NETWORKDAYS(start, end, holidays)
        4

    Cost: O(n) where n is the number of days between dates
    """
    return _core_networkdays(start_date, end_date, holidays)

NETWORKDAYS_INTL(start_date: datetime, end_date: datetime, weekend: Union[int, str] = 1, holidays: Optional[List[datetime]] = None) -> int

Returns working days between two dates with custom weekend parameters.

Description

Equivalent to Excel's NETWORKDAYS.INTL function. Calculates the number of working days between two dates, allowing customization of which days are considered weekends.

Parameters:

Name Type Description Default
start_date datetime

The start date.

 required
end_date datetime

The end date.

 required
weekend Union[int, str]

Weekend definition. Int 1-7 for preset patterns, or string of 0s and 1s where 1=weekend. Defaults to 1.

 1
holidays Optional[List[datetime]]

List of holiday dates. Defaults to None.

 None

Returns:

Name Type Description
int int

Number of working days.
Usage Example

from datetime import datetime from shortfx.fxExcel.date_formulas import NETWORKDAYS_INTL start = datetime(2025, 1, 6) end = datetime(2025, 1, 10) NETWORKDAYS_INTL(start, end) # Standard Sat-Sun weekend 5 NETWORKDAYS_INTL(start, end, weekend=2) # Sun-Mon weekend 4

Cost: O(n) where n is the number of days between dates

Source code in shortfx/fxExcel/date_formulas.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
def NETWORKDAYS_INTL(start_date: datetime, end_date: datetime, weekend: Union[int, str] = 1, holidays: Optional[List[datetime]] = None) -> int:
    """Returns working days between two dates with custom weekend parameters.

    Description:
        Equivalent to Excel's NETWORKDAYS.INTL function. Calculates the number
        of working days between two dates, allowing customization of which days
        are considered weekends.

    Args:
        start_date (datetime): The start date.
        end_date (datetime): The end date.
        weekend (Union[int, str], optional): Weekend definition. Int 1-7 for preset patterns,
                                            or string of 0s and 1s where 1=weekend. Defaults to 1.
        holidays (Optional[List[datetime]], optional): List of holiday dates. Defaults to None.

    Returns:
        int: Number of working days.

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxExcel.date_formulas import NETWORKDAYS_INTL
        >>> start = datetime(2025, 1, 6)
        >>> end = datetime(2025, 1, 10)
        >>> NETWORKDAYS_INTL(start, end)  # Standard Sat-Sun weekend
        5
        >>> NETWORKDAYS_INTL(start, end, weekend=2)  # Sun-Mon weekend
        4

    Cost: O(n) where n is the number of days between dates
    """
    return _core_networkdays_intl(start_date, end_date, weekend, holidays)

NOW() -> float

Returns the Excel serial number of the current date and time. Excel/Spanish name: AHORA

Description: Returns the current date and time as an Excel serial number. Integer part is the date, fractional part is the time.

Returns: float: The Excel serial number representing the current date and time.

Raises: None

Usage Example: >>> # Output depends on current date and time >>> NOW() # e.g., 45667.625 for January 15, 2025, 3:00 PM 45667.625

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
def NOW() -> float:
    """
    Returns the Excel serial number of the current date and time.
    Excel/Spanish name: AHORA

    **Description:**
    Returns the current date and time as an Excel serial number.
    Integer part is the date, fractional part is the time.

    **Returns:**
        float: The Excel serial number representing the current date and time.

    **Raises:**
        None

    **Usage Example:**
        >>> # Output depends on current date and time
        >>> NOW()  # e.g., 45667.625 for January 15, 2025, 3:00 PM
        45667.625

    **Cost:** O(1)
    """
    return _now_to_excel_serial()

SECOND(serial_number: Union[float, datetime]) -> int

Converts an Excel serial number to a second value. Excel/Spanish name: SECOND (SEGUNDO in Spanish)

Description: Extracts the second component (0-59) from an Excel serial number or datetime object.

Args: serial_number: An Excel serial number or datetime object.

Returns: int: The second (0-59).

Raises: ValueError: If the serial number is invalid.

Usage Example: >>> from datetime import datetime >>> SECOND(datetime(2025, 1, 15, 14, 30, 45)) 45 >>> SECOND(0.604224537) # Approximately 2:30:05 PM 5

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
def SECOND(serial_number: Union[float, datetime]) -> int:
    """
    Converts an Excel serial number to a second value.
    Excel/Spanish name: SECOND (SEGUNDO in Spanish)

    **Description:**
    Extracts the second component (0-59) from an Excel serial number or datetime object.

    **Args:**
        serial_number: An Excel serial number or datetime object.

    **Returns:**
        int: The second (0-59).

    **Raises:**
        ValueError: If the serial number is invalid.

    **Usage Example:**
        >>> from datetime import datetime
        >>> SECOND(datetime(2025, 1, 15, 14, 30, 45))
        45
        >>> SECOND(0.604224537)  # Approximately 2:30:05 PM
        5

    **Cost:** O(1)
    """
    return _excel_serial_to_second(serial_number)

TIME(hour: int, minute: int, second: int) -> float

Returns the Excel serial number for a particular time. Excel/Spanish name: HORA (as noun in Spanish)

Description: Converts hours, minutes, and seconds into an Excel serial number representing the time as a fraction of a day.

Args: hour: The hour (0-23). minute: The minute (0-59). second: The second (0-59).

Returns: float: The Excel serial number representing the time (fraction of a day).

Raises: ValueError: If hour, minute, or second are out of range.

Usage Example: >>> TIME(12, 0, 0) # 12:00 PM 0.5 >>> TIME(6, 0, 0) # 6:00 AM 0.25 >>> TIME(18, 30, 0) # 6:30 PM 0.7708333333333334

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
def TIME(hour: int, minute: int, second: int) -> float:
    """
    Returns the Excel serial number for a particular time.
    Excel/Spanish name: HORA (as noun in Spanish)

    **Description:**
    Converts hours, minutes, and seconds into an Excel serial number representing
    the time as a fraction of a day.

    **Args:**
        hour: The hour (0-23).
        minute: The minute (0-59).
        second: The second (0-59).

    **Returns:**
        float: The Excel serial number representing the time (fraction of a day).

    **Raises:**
        ValueError: If hour, minute, or second are out of range.

    **Usage Example:**
        >>> TIME(12, 0, 0)  # 12:00 PM
        0.5
        >>> TIME(6, 0, 0)  # 6:00 AM
        0.25
        >>> TIME(18, 30, 0)  # 6:30 PM
        0.7708333333333334

    **Cost:** O(1)
    """
    return _time_to_excel_serial(hour, minute, second)

TIMEVALUE(time_text: str) -> float

Converts a time in text format to a serial number.

Description

Equivalent to Excel's TIMEVALUE function. Converts a time represented as text into an Excel serial number (fraction of a 24-hour day).

Parameters:

Name Type Description Default
time_text str

Time in "HH:MM:SS" format.

 required

Returns:

Name Type Description
float float

Excel serial number representing the time.
Usage Example

from shortfx.fxExcel.date_formulas import TIMEVALUE TIMEVALUE("12:00:00") # Noon 0.5 TIMEVALUE("18:30:00") # 6:30 PM 0.7708333333333334

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
def TIMEVALUE(time_text: str) -> float:
    """Converts a time in text format to a serial number.

    Description:
        Equivalent to Excel's TIMEVALUE function. Converts a time represented
        as text into an Excel serial number (fraction of a 24-hour day).

    Args:
        time_text (str): Time in "HH:MM:SS" format.

    Returns:
        float: Excel serial number representing the time.

    Usage Example:
        >>> from shortfx.fxExcel.date_formulas import TIMEVALUE
        >>> TIMEVALUE("12:00:00")  # Noon
        0.5
        >>> TIMEVALUE("18:30:00")  # 6:30 PM
        0.7708333333333334

    Cost: O(1)
    """
    return _core_time_to_day_fraction(time_text)

TODAY() -> float

Returns the Excel serial number of the current date. Excel/Spanish name: HOY

Description: Returns the current date as an Excel serial number (integer part only, no time).

Returns: float: The Excel serial number representing today's date.

Raises: None

Usage Example: >>> # Output depends on current date >>> TODAY() # e.g., 45667.0 for January 15, 2025 45667.0

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
def TODAY() -> float:
    """
    Returns the Excel serial number of the current date.
    Excel/Spanish name: HOY

    **Description:**
    Returns the current date as an Excel serial number (integer part only, no time).

    **Returns:**
        float: The Excel serial number representing today's date.

    **Raises:**
        None

    **Usage Example:**
        >>> # Output depends on current date
        >>> TODAY()  # e.g., 45667.0 for January 15, 2025
        45667.0

    **Cost:** O(1)
    """
    today = datetime.now().date()
    return _int_date_to_excel_serial(today.year, today.month, today.day)

WEEKDAY(serial_number: Union[float, datetime], return_type: int = 1) -> int

Converts an Excel serial number to a day of the week. Excel/Spanish name: DIASEM

Description: Returns the day of the week for a given date. The return_type parameter determines how the week is numbered (1-7 or 0-6).

Args: serial_number: An Excel serial number or datetime object. return_type: Determines the week numbering system: - 1 (default): Sunday=1 through Saturday=7 - 2: Monday=1 through Sunday=7 - 3: Monday=0 through Sunday=6

Returns: int: The day of the week according to the return_type.

Raises: ValueError: If return_type is not 1, 2, or 3.

Usage Example: >>> from datetime import datetime >>> # January 15, 2025 is a Wednesday >>> WEEKDAY(datetime(2025, 1, 15)) # Wednesday with Sunday=1 4 >>> WEEKDAY(datetime(2025, 1, 15), 2) # Wednesday with Monday=1 3 >>> WEEKDAY(datetime(2025, 1, 15), 3) # Wednesday with Monday=0 2

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
def WEEKDAY(serial_number: Union[float, datetime], return_type: int = 1) -> int:
    """
    Converts an Excel serial number to a day of the week.
    Excel/Spanish name: DIASEM

    **Description:**
    Returns the day of the week for a given date. The return_type parameter
    determines how the week is numbered (1-7 or 0-6).

    **Args:**
        serial_number: An Excel serial number or datetime object.
        return_type: Determines the week numbering system:
            - 1 (default): Sunday=1 through Saturday=7
            - 2: Monday=1 through Sunday=7
            - 3: Monday=0 through Sunday=6

    **Returns:**
        int: The day of the week according to the return_type.

    **Raises:**
        ValueError: If return_type is not 1, 2, or 3.

    **Usage Example:**
        >>> from datetime import datetime
        >>> # January 15, 2025 is a Wednesday
        >>> WEEKDAY(datetime(2025, 1, 15))  # Wednesday with Sunday=1
        4
        >>> WEEKDAY(datetime(2025, 1, 15), 2)  # Wednesday with Monday=1
        3
        >>> WEEKDAY(datetime(2025, 1, 15), 3)  # Wednesday with Monday=0
        2

    **Cost:** O(1)
    """
    return _excel_serial_to_weekday(serial_number, return_type)

WEEKNUM(serial_number: Union[float, datetime], return_type: int = 1) -> int

Converts a serial number to a week number.

Description

Equivalent to Excel's WEEKNUM function. Returns the week number for a date. The week number indicates where the week falls numerically within a year.

Parameters:

Name Type Description Default
serial_number Union[float, datetime]

Date as Excel serial number or datetime.

 required
return_type int

System to use (1=week starts Sunday, 21=ISO week). Defaults to 1.

 1

Returns:

Name Type Description
int int

Week number of the year.
Usage Example

from datetime import datetime from shortfx.fxExcel.date_formulas import WEEKNUM WEEKNUM(datetime(2025, 1, 1), return_type=1) 1 WEEKNUM(datetime(2025, 1, 1), return_type=21) 1

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
def WEEKNUM(serial_number: Union[float, datetime], return_type: int = 1) -> int:
    """Converts a serial number to a week number.

    Description:
        Equivalent to Excel's WEEKNUM function. Returns the week number for a
        date. The week number indicates where the week falls numerically within a year.

    Args:
        serial_number (Union[float, datetime]): Date as Excel serial number or datetime.
        return_type (int, optional): System to use (1=week starts Sunday, 21=ISO week).
                                    Defaults to 1.

    Returns:
        int: Week number of the year.

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxExcel.date_formulas import WEEKNUM
        >>> WEEKNUM(datetime(2025, 1, 1), return_type=1)
        1
        >>> WEEKNUM(datetime(2025, 1, 1), return_type=21)
        1

    Cost: O(1)
    """
    if isinstance(serial_number, float):
        dt = datetime(1899, 12, 30) + timedelta(days=serial_number)
    else:
        dt = serial_number

    return _core_week_number(dt, system=21 if return_type == 21 else 1)

WORKDAY(start_date: Union[float, datetime], days: int, holidays: Optional[List[datetime]] = None) -> float

Returns the date after a number of working days.

Description

Equivalent to Excel's WORKDAY function. Returns the Excel serial number of the date before or after a specified number of working days.

Parameters:

Name Type Description Default
start_date Union[float, datetime]

Starting date.

 required
days int

Number of working days (positive for future, negative for past).

 required
holidays Optional[List[datetime]]

List of holiday dates to exclude. Defaults to None.

 None

Returns:

Name Type Description
float float

Excel serial number of the resulting date.
Usage Example

from datetime import datetime from shortfx.fxDate.date_excel import WORKDAY start = datetime(2025, 1, 6) # Monday WORKDAY(start, 5) # 5 working days later 45662.0 WORKDAY(start, -5) # 5 working days earlier 45652.0

Cost: O(n) where n is the number of days

Source code in shortfx/fxExcel/date_formulas.py 
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
def WORKDAY(start_date: Union[float, datetime], days: int, holidays: Optional[List[datetime]] = None) -> float:
    """Returns the date after a number of working days.

    Description:
        Equivalent to Excel's WORKDAY function. Returns the Excel serial number
        of the date before or after a specified number of working days.

    Args:
        start_date (Union[float, datetime]): Starting date.
        days (int): Number of working days (positive for future, negative for past).
        holidays (Optional[List[datetime]], optional): List of holiday dates to exclude.
                                                       Defaults to None.

    Returns:
        float: Excel serial number of the resulting date.

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxDate.date_excel import WORKDAY
        >>> start = datetime(2025, 1, 6)  # Monday
        >>> WORKDAY(start, 5)  # 5 working days later
        45662.0
        >>> WORKDAY(start, -5)  # 5 working days earlier
        45652.0

    Cost: O(n) where n is the number of days
    """
    return _core_workday(start_date, days, holidays)

WORKDAY_INTL(start_date: Union[float, datetime], days: int, weekend: Union[int, str] = 1, holidays: Optional[List[datetime]] = None) -> float

Returns the date after working days with custom weekend.

Description

Equivalent to Excel's WORKDAY.INTL function. Returns the Excel serial number of the date before or after a specified number of working days with custom weekend parameters.

Parameters:

Name Type Description Default
start_date Union[float, datetime]

Starting date.

 required
days int

Number of working days to add or subtract.

 required
weekend Union[int, str]

Weekend definition. Defaults to 1 (Sat-Sun).

 1
holidays Optional[List[datetime]]

List of holiday dates. Defaults to None.

 None

Returns:

Name Type Description
float float

Excel serial number of the resulting date.
Usage Example

from datetime import datetime from shortfx.fxDate.date_excel import WORKDAY_INTL start = datetime(2025, 1, 6) # Monday WORKDAY_INTL(start, 5) # 5 working days later 45662.0 WORKDAY_INTL(start, 5, weekend=2) # With Sun-Mon weekend 45663.0

Cost: O(n) where n is the number of days

Source code in shortfx/fxExcel/date_formulas.py 
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
def WORKDAY_INTL(start_date: Union[float, datetime], days: int, weekend: Union[int, str] = 1, holidays: Optional[List[datetime]] = None) -> float:
    """Returns the date after working days with custom weekend.

    Description:
        Equivalent to Excel's WORKDAY.INTL function. Returns the Excel serial number
        of the date before or after a specified number of working days with custom
        weekend parameters.

    Args:
        start_date (Union[float, datetime]): Starting date.
        days (int): Number of working days to add or subtract.
        weekend (Union[int, str], optional): Weekend definition. Defaults to 1 (Sat-Sun).
        holidays (Optional[List[datetime]], optional): List of holiday dates. Defaults to None.

    Returns:
        float: Excel serial number of the resulting date.

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxDate.date_excel import WORKDAY_INTL
        >>> start = datetime(2025, 1, 6)  # Monday
        >>> WORKDAY_INTL(start, 5)  # 5 working days later
        45662.0
        >>> WORKDAY_INTL(start, 5, weekend=2)  # With Sun-Mon weekend
        45663.0

    Cost: O(n) where n is the number of days
    """
    return _core_workday_intl(start_date, days, weekend, holidays)

YEAR(serial_number: Union[float, datetime]) -> int

Converts an Excel serial number to a year value. Excel/Spanish name: YEAR (AÑO in Spanish)

Description: Extracts the year component from an Excel serial number or datetime object.

Args: serial_number: An Excel serial number or datetime object.

Returns: int: The year (e.g., 2025).

Raises: ValueError: If the serial number is invalid.

Usage Example: >>> from datetime import datetime >>> YEAR(45667.0) # January 15, 2025 2025 >>> YEAR(datetime(2024, 12, 31)) 2024

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
def YEAR(serial_number: Union[float, datetime]) -> int:
    """
    Converts an Excel serial number to a year value.
    Excel/Spanish name: YEAR (AÑO in Spanish)

    **Description:**
    Extracts the year component from an Excel serial number or datetime object.

    **Args:**
        serial_number: An Excel serial number or datetime object.

    **Returns:**
        int: The year (e.g., 2025).

    **Raises:**
        ValueError: If the serial number is invalid.

    **Usage Example:**
        >>> from datetime import datetime
        >>> YEAR(45667.0)  # January 15, 2025
        2025
        >>> YEAR(datetime(2024, 12, 31))
        2024

    **Cost:** O(1)
    """
    return _excel_serial_to_year(serial_number)

YEARFRAC(start_date: datetime, end_date: datetime, basis: int = 0) -> float

Returns the fraction of year between two dates.

Description

Equivalent to Excel's YEARFRAC function. Calculates the fraction of the year represented by the number of whole days between two dates.

Parameters:

Name Type Description Default
start_date datetime

The start date.

 required
end_date datetime

The end date.

 required
basis int

Day count basis to use (0=US 30/360, 1=Actual/Actual). Defaults to 0.

 0

Returns:

Name Type Description
float float

Fraction of year between the dates.
Usage Example

from datetime import datetime from shortfx.fxExcel.date_formulas import YEARFRAC start = datetime(2025, 1, 1) end = datetime(2025, 7, 1) YEARFRAC(start, end, basis=0) # US 30/360 0.5 YEARFRAC(start, end, basis=1) # Actual/Actual 0.4958904109589041

Cost: O(1)

Source code in shortfx/fxExcel/date_formulas.py 
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
def YEARFRAC(start_date: datetime, end_date: datetime, basis: int = 0) -> float:
    """Returns the fraction of year between two dates.

    Description:
        Equivalent to Excel's YEARFRAC function. Calculates the fraction of the
        year represented by the number of whole days between two dates.

    Args:
        start_date (datetime): The start date.
        end_date (datetime): The end date.
        basis (int, optional): Day count basis to use (0=US 30/360, 1=Actual/Actual).
                              Defaults to 0.

    Returns:
        float: Fraction of year between the dates.

    Usage Example:
        >>> from datetime import datetime
        >>> from shortfx.fxExcel.date_formulas import YEARFRAC
        >>> start = datetime(2025, 1, 1)
        >>> end = datetime(2025, 7, 1)
        >>> YEARFRAC(start, end, basis=0)  # US 30/360
        0.5
        >>> YEARFRAC(start, end, basis=1)  # Actual/Actual
        0.4958904109589041

    Cost: O(1)
    """
    return _core_year_fraction(start_date, end_date, basis)