# `pybizday_utils`: Python Business Day Utilities

![GitHub top language](https://img.shields.io/github/languages/top/hmasdev/pybizday_utils)
![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/hmasdev/pybizday_utils?sort=semver)
![GitHub](https://img.shields.io/github/license/hmasdev/pybizday_utils)
![GitHub last commit](https://img.shields.io/github/last-commit/hmasdev/pybizday_utils)

`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](./pyproject.toml) for other dependencies

### Install pybizday_utils with pip

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

## 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:

```python
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:

```python
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](#customize-holidays) or [Customize the default holidays](#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:

```python
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:

```python
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:

```python
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](./pyproject.toml) for other dependencies

### Development Steps

1. Fork the repository: [https://github.com/hmasdev/pybizday_utils/fork](https://github.com/hmasdev/pybizday_utils/fork)
2. Clone the forked repository:

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

3. Setup the development environment:

   ```bash
   uv sync --dev
   ```

4. Checkout your working branch:

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

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

   ```bash
   uv run nox -s test  # or uv run pytest
   uv run nox -s lint  # or uv run ruff check src tests
   uv run nox -s mypy  # or uv run mypy src tests
   ```

6. Commit and push your changes:

   ```bash
   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](https://github.com/hmasdev/pybizday_utils/compare) to the main repository.

## License

[MIT](./LICENSE)

## Author

- [hmasdev](https://github.com/hmasdev)
