pybizday-utils 0.0.0b0

`pybizday_utils` is a Python library that provides utilities for calculating business days, including the ability to customize holidays and workdays.

pybizday_utils: Python Business Day Utilities :calendar: :calendar: :calendar:

pybizday_utils is a Python library that provides utilities for calculating business days, including the ability to customize holidays and workdays. It is designed to be simple and easy to use, making it a great choice for developers who need to work with business days in their applications.

Installation

Requirements

• Python 3.10 or later
• pip
• see pyproject.toml for other dependencies

Install pybizday_utils with pip

pip install -U pybizday_utils

pip install -U git+https://github.com/hmasdev/pybizday_utils.git

Note that the second command will install the latest version from the main branch, which may not be stable.

How to Use

pybizday_utils provides the following two main features:

1. Calculate or count business days:
   • get the n-th business day after a given date;
   • get the n-th business day before a given date;
   • get the iterator of business days between two dates;
   • count business days between two dates;
2. Calculate business days in month.
   • get the first business day of the month;
   • get the last business day of the month;
   • add years and months to a date considering business days. e.g. transform a business end of month to a business end of month.

In this section, some examples are provided to illustrate how to use the library. If you want to know the defails, see the docstrings of each function.

The following is an example of the first feature:

from datetime import date
from pybizday_utils import (
    bizday_range,
    count_bizdays,
    get_n_next_bizday,
    get_n_prev_bizday,
    get_next_bizday,
    get_prev_bizday,
    is_bizday,
)

# Get the next business day after a given date
next_bizday = get_next_bizday(date(2025, 3, 28))
print(next_bizday)  # Output: 2025-03-31

# Get the previous business day before a given date
prev_bizday = get_prev_bizday(date(2025, 3, 31))
print(prev_bizday)  # Output: 2025-03-28

# Get the n-th business day after a given date
n_next_bizday = get_n_next_bizday(date(2025, 3, 28), 2)
print(n_next_bizday)  # Output: 2025-04-01

# Get the n-th business day before a given date
n_prev_bizday = get_n_prev_bizday(date(2025, 3, 31), 2)
print(n_prev_bizday)  # Output: 2025-03-27
# Also works with negative numbers
n_prev_bizday_ = get_n_prev_bizday(date(2025, 3, 31), -2)
print(n_prev_bizday_)  # Output: 2025-03-27

# Get the iterator of business days between two dates
bizdays = bizday_range(date(2025, 3, 28), date(2025, 4, 4))
for bizday in bizdays:
    print(bizday)  # Output: 2025-03-28, 2025-03-31, 2025-04-01, 2025-04-02, 2025-04-03, 2025-04-04

# Count business days between two dates
count = count_bizdays(date(2025, 3, 28), date(2025, 4, 4))
print(count)  # Output: 6

On the other hand, the second feature is useful for calculating business days in a month. For example:

from datetime import date
from pybizday_utils import (
    add_months,
    add_years,
    get_biz_start_of_month,
    get_biz_end_of_month,
)

# Get the first business day of the month
first_bizday = get_biz_start_of_month(date(2025, 3, 28))
print(first_bizday)  # Output: 2025-03-03

# Get the last business day of the month
last_bizday = get_biz_end_of_month(date(2024, 11, 15))
print(last_bizday)  # Output: 2024-11-29

# Add months to a date considering business days
add_months_bizday = add_months(date(2024, 10, 31), 1, bizeom2bizeom=True)
print(add_months_bizday)  # Output: 2024-11-29

# Add years to a date considering business days
add_years_bizday = add_years(date(2023, 11, 30), 1, bizeom2bizeom=True)
print(add_years_bizday)  # Output: 2024-11-29

Note that only Saturday and Sunday are considered holidays in default. If you want to customize the holidays, see Customize holidays or Customize the default holidays.

Customize holidays

If you want to customize the holidays, pass is_holiday parameter to each function. For example, you can use a lambda function to define your own holidays, assuming that 1/1 and 4/3 are holidays:

from datetime import date
from pybizday_utils import (
    bizday_range,
    get_next_bizday,
    get_prev_bizday,
)

# Define your own holidays
def my_is_holiday(date):
    return date.month == 1 and date.day == 1 or date.month == 4 and date.day == 3


# Get the next business day after a given date
next_bizday = get_next_bizday(date(2025, 4, 2), is_holiday=my_is_holiday)
print(next_bizday)  # Output: 2025-04-04

# Get the previous business day before a given date
prev_bizday = get_prev_bizday(date(2025, 4, 4), is_holiday=my_is_holiday)
print(prev_bizday)  # Output: 2025-04-02

# Get the iterator of business days between two dates
bizdays = bizday_range(date(2025, 4, 2), date(2025, 4, 6), is_holiday=my_is_holiday)
for bizday in bizdays:
    print(bizday)  # Output: 2025-04-02, 2025-04-04, 2025-04-05, 2025-04-06

Note that the default is_holiday function, which checks if a date is Saturday or Sunday, is not used in this case.

Customize the default holidays

You can also customize the default holidays by using the set_default_holidays function. This customization will affect all functions that use the default holidays. For example, you can set the default holidays to be 1/1 and 4/3:

from datetime import date
from pybizday_utils import (
    get_next_bizday,
    get_prev_bizday,
)
from pybizday_utils.default_holiday_utils import (
    add_global_is_holiday_funcs,
    remove_global_is_holiday_funcs,
)


def is_3rd_apr(date):
    return date.month == 4 and date.day == 3


# In default
# Get the next business day after a given date
next_bizday = get_next_bizday(date(2025, 4, 2))
print(next_bizday)  # Output: 2025-04-03

# Add the global holidays
add_global_is_holiday_funcs(is_3rd_apr)

# Get the next business day after a given date
next_bizday = get_next_bizday(date(2025, 4, 2))
print(next_bizday)  # Output: 2025-04-04

# Remove the global holidays
remove_global_is_holiday_funcs("is_3rd_apr")

# Get the next business day after a given date
next_bizday = get_next_bizday(date(2025, 4, 2))
print(next_bizday)  # Output: 2025-04-03

If you want to customize the global default holidays temporarily, use with_is_holiday_funcs context manager.

For example:

from datetime import date
from pybizday_utils import get_next_bizday
from pybizday_utils.default_holiday_utils import (
    with_is_holiday_funcs,
)


def is_3rd_apr(date):
    return date.month == 4 and date.day == 3


# In default
# Get the next business day after a given date
next_bizday = get_next_bizday(date(2025, 4, 2))
print(next_bizday)  # Output: 2025-04-03

# Add the global holidays temporarily
with with_is_holiday_funcs(is_3rd_apr):
    # Get the next business day after a given date
    next_bizday = get_next_bizday(date(2025, 4, 2))
    print(next_bizday)  # Output: 2025-04-04

# Get the next business day after a given date
next_bizday = get_next_bizday(date(2025, 4, 2))
print(next_bizday)  # Output: 2025-04-03

Contribution Guide

Development Requirements

• Python 3.10 or later
• uv
• see pyproject.toml for other dependencies

Development Steps

1. Fork the repository: https://github.com/hmasdev/pybizday_utils/fork

2. Clone the forked repository:

   git clone https://github.com/{your_username}/pybizday_utils
   cd pybizday_utils
   

3. Setup the development environment:

   uv sync --dev
   

4. Checkout your working branch:

   git switch -c {your_branch_name}
   # or
   # git checkout -b {your_branch_name}
   

5. Test and lint your changes and check type hints:

   uv run nox -s test
   uv run nox -s lint
   uv run nox -s mypy
   

   In above commands, each command is run with python 3.10, 3.11, 3.12, and 3.13. If you want to run with a specific version, use --python option. For example:

   uv run nox -s test --python 3.10
   uv run nox -s lint --python 3.11
   uv run nox -s mypy --python 3.12
   

   or

   uv run pytest
   uv run ruff check src tests
   uv run mypy src tests
   

6. Commit and push your changes:

   git add .
   git commit -m "Your commit message"
   git push origin {your_branch_name}
   # git push -u origin {your_branch_name} # if you are pushing for the first time
   

7. Create a pull request to the main repository.

License

MIT

Author

• hmasdev