{"id":27237995,"url":"https://github.com/hmasdev/pybizday_utils","last_synced_at":"2026-02-24T06:40:46.892Z","repository":{"id":286298505,"uuid":"960990253","full_name":"hmasdev/pybizday_utils","owner":"hmasdev","description":"a Python library that provides utilities for calculating business days, including the ability to customize holidays and workdays","archived":false,"fork":false,"pushed_at":"2025-04-11T13:39:43.000Z","size":158,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T21:55:51.340Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hmasdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-04-05T14:15:41.000Z","updated_at":"2025-04-11T13:39:46.000Z","dependencies_parsed_at":"2025-04-05T15:40:45.536Z","dependency_job_id":null,"html_url":"https://github.com/hmasdev/pybizday_utils","commit_stats":null,"previous_names":["hmasdev/pybizday_utils"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmasdev%2Fpybizday_utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmasdev%2Fpybizday_utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmasdev%2Fpybizday_utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmasdev%2Fpybizday_utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hmasdev","download_url":"https://codeload.github.com/hmasdev/pybizday_utils/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248487729,"owners_count":21112188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-10T18:59:41.476Z","updated_at":"2026-02-24T06:40:46.864Z","avatar_url":"https://github.com/hmasdev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `pybizday_utils`: Python Business Day Utilities :calendar:\n\n![GitHub top language](https://img.shields.io/github/languages/top/hmasdev/pybizday_utils)\n![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/hmasdev/pybizday_utils?sort=semver)\n[![LICENSE](https://img.shields.io/github/license/hmasdev/pybizday_utils)](./LICENSE)\n![GitHub last commit](https://img.shields.io/github/last-commit/hmasdev/pybizday_utils)\n[![Scheduled Test](https://github.com/hmasdev/pybizday_utils/actions/workflows/on-scheduled.yaml/badge.svg)](https://github.com/hmasdev/pybizday_utils/actions/workflows/on-scheduled.yaml)\n[![PyPI version](https://badge.fury.io/py/pybizday_utils.svg)](https://pypi.org/project/pybizday_utils/)\n\n`pybizday_utils` is a Python library that provides utilities for calculating business days, including the ability to customize holidays and workdays.\nIt 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.\n\n## Installation\n\n### Requirements\n\n- Python 3.10 or later\n- `pip`\n- see [pyproject.toml](./pyproject.toml) for other dependencies\n\n### Install `pybizday_utils` with pip\n\n```bash\npip install -U pybizday_utils\n```\n\n```bash\npip install -U git+https://github.com/hmasdev/pybizday_utils.git\n```\n\nNote that the second command will install the latest version from the main branch, which may not be stable.\n\n### Install `pybizday_utils` by building from source\n\nSee [How to Build](#how-to-build) section for more details.\n\n## How to Use\n\n`pybizday_utils` provides the following two main features:\n\n1. **Calculate or count business days**:\n   - get the n-th business day after a given date;\n   - get the n-th business day before a given date;\n   - get the iterator of business days between two dates;\n   - count business days between two dates;\n2. **Calculate business days in month**.\n   - get the first business day of the month;\n   - get the last business day of the month;\n   - add years and months to a date considering business days. e.g. transform a business end of month to a business end of month.\n\nIn this section, some examples are provided to illustrate how to use the library.\nIf you want to know the defails, see the docstrings of each function.\n\nThe following is an example of the first feature:\n\n```python\nfrom datetime import date\nfrom pybizday_utils import (\n    bizday_range,\n    count_bizdays,\n    get_n_next_bizday,\n    get_n_prev_bizday,\n    get_next_bizday,\n    get_prev_bizday,\n    is_bizday,\n)\n\n# Get the next business day after a given date\nnext_bizday = get_next_bizday(date(2025, 3, 28))\nprint(next_bizday)  # Output: 2025-03-31\n\n# Get the previous business day before a given date\nprev_bizday = get_prev_bizday(date(2025, 3, 31))\nprint(prev_bizday)  # Output: 2025-03-28\n\n# Get the n-th business day after a given date\nn_next_bizday = get_n_next_bizday(date(2025, 3, 28), 2)\nprint(n_next_bizday)  # Output: 2025-04-01\n\n# Get the n-th business day before a given date\nn_prev_bizday = get_n_prev_bizday(date(2025, 3, 31), 2)\nprint(n_prev_bizday)  # Output: 2025-03-27\n# Also works with negative numbers\nn_prev_bizday_ = get_n_prev_bizday(date(2025, 3, 31), -2)\nprint(n_prev_bizday_)  # Output: 2025-03-27\n\n# Get the iterator of business days between two dates\nbizdays = bizday_range(date(2025, 3, 28), date(2025, 4, 4))\nfor bizday in bizdays:\n    print(bizday)  # Output: 2025-03-28, 2025-03-31, 2025-04-01, 2025-04-02, 2025-04-03, 2025-04-04\n\n# Count business days between two dates\ncount = count_bizdays(date(2025, 3, 28), date(2025, 4, 4))\nprint(count)  # Output: 6\n```\n\nOn the other hand, the second feature is useful for calculating business days in a month. For example:\n\n```python\nfrom datetime import date\nfrom pybizday_utils import (\n    add_months,\n    add_years,\n    get_biz_start_of_month,\n    get_biz_end_of_month,\n)\n\n# Get the first business day of the month\nfirst_bizday = get_biz_start_of_month(date(2025, 3, 28))\nprint(first_bizday)  # Output: 2025-03-03\n\n# Get the last business day of the month\nlast_bizday = get_biz_end_of_month(date(2024, 11, 15))\nprint(last_bizday)  # Output: 2024-11-29\n\n# Add months to a date considering business days\nadd_months_bizday = add_months(date(2024, 10, 31), 1, bizeom2bizeom=True)\nprint(add_months_bizday)  # Output: 2024-11-29\n\n# Add years to a date considering business days\nadd_years_bizday = add_years(date(2023, 11, 30), 1, bizeom2bizeom=True)\nprint(add_years_bizday)  # Output: 2024-11-29\n```\n\n**Note that only Saturday and Sunday are considered holidays in default**.\nIf you want to customize the holidays, see [Customize holidays](#customize-holidays) or [Customize the default holidays](#customize-the-default-holidays).\n\n### Customize holidays\n\nIf you want to customize the holidays, pass `is_holiday` parameter to each function.\nFor example, you can use a lambda function to define your own holidays, assuming that 1/1 and 4/3 are holidays:\n\n```python\nfrom datetime import date\nfrom pybizday_utils import (\n    bizday_range,\n    get_next_bizday,\n    get_prev_bizday,\n)\n\n# Define your own holidays\ndef my_is_holiday(date):\n    return date.month == 1 and date.day == 1 or date.month == 4 and date.day == 3\n\n\n# Get the next business day after a given date\nnext_bizday = get_next_bizday(date(2025, 4, 2), is_holiday=my_is_holiday)\nprint(next_bizday)  # Output: 2025-04-04\n\n# Get the previous business day before a given date\nprev_bizday = get_prev_bizday(date(2025, 4, 4), is_holiday=my_is_holiday)\nprint(prev_bizday)  # Output: 2025-04-02\n\n# Get the iterator of business days between two dates\nbizdays = bizday_range(date(2025, 4, 2), date(2025, 4, 6), is_holiday=my_is_holiday)\nfor bizday in bizdays:\n    print(bizday)  # Output: 2025-04-02, 2025-04-04, 2025-04-05, 2025-04-06\n```\n\n**Note that the default `is_holiday function`, which checks if a date is Saturday or Sunday, is not used in this case.**\n\n### Customize the default holidays\n\nYou can also customize the default holidays by using the `set_default_holidays` function.\nThis customization will affect all functions that use the default holidays.\nFor example, you can set the default holidays to be 1/1 and 4/3:\n\n```python\nfrom datetime import date\nfrom pybizday_utils import (\n    get_next_bizday,\n    get_prev_bizday,\n)\nfrom pybizday_utils.default_holiday_utils import (\n    add_global_is_holiday_funcs,\n    remove_global_is_holiday_funcs,\n)\n\n\ndef is_3rd_apr(date):\n    return date.month == 4 and date.day == 3\n\n\n# In default\n# Get the next business day after a given date\nnext_bizday = get_next_bizday(date(2025, 4, 2))\nprint(next_bizday)  # Output: 2025-04-03\n\n# Add the global holidays\nadd_global_is_holiday_funcs(is_3rd_apr)\n\n# Get the next business day after a given date\nnext_bizday = get_next_bizday(date(2025, 4, 2))\nprint(next_bizday)  # Output: 2025-04-04\n\n# Remove the global holidays\nremove_global_is_holiday_funcs(\"is_3rd_apr\")\n\n# Get the next business day after a given date\nnext_bizday = get_next_bizday(date(2025, 4, 2))\nprint(next_bizday)  # Output: 2025-04-03\n```\n\nIf you want to customize the global default holidays temporarily, use `with_is_holiday_funcs` context manager.\n\nFor example:\n\n```python\nfrom datetime import date\nfrom pybizday_utils import get_next_bizday\nfrom pybizday_utils.default_holiday_utils import (\n    with_is_holiday_funcs,\n)\n\n\ndef is_3rd_apr(date):\n    return date.month == 4 and date.day == 3\n\n\n# In default\n# Get the next business day after a given date\nnext_bizday = get_next_bizday(date(2025, 4, 2))\nprint(next_bizday)  # Output: 2025-04-03\n\n# Add the global holidays temporarily\nwith with_is_holiday_funcs(is_3rd_apr):\n    # Get the next business day after a given date\n    next_bizday = get_next_bizday(date(2025, 4, 2))\n    print(next_bizday)  # Output: 2025-04-04\n\n# Get the next business day after a given date\nnext_bizday = get_next_bizday(date(2025, 4, 2))\nprint(next_bizday)  # Output: 2025-04-03\n```\n\n## Contribution Guide\n\n### Development Requirements\n\n- Python 3.10 or later\n- `uv`\n- see [pyproject.toml](./pyproject.toml) for other dependencies\n\n### How to Develop\n\n1. Fork the repository: [https://github.com/hmasdev/pybizday_utils/fork](https://github.com/hmasdev/pybizday_utils/fork)\n2. Clone the forked repository:\n\n   ```bash\n   git clone https://github.com/{your_username}/pybizday_utils\n   cd pybizday_utils\n   ```\n\n3. Setup the development environment:\n\n   ```bash\n   uv sync --dev\n   ```\n\n4. Checkout your working branch:\n\n   ```bash\n   git switch -c {your_branch_name}\n   # or\n   # git checkout -b {your_branch_name}\n   ```\n\n5. Test and lint your changes and check type hints:\n\n   ```bash\n   uv run nox -s test\n   uv run nox -s lint\n   uv run nox -s mypy\n   ```\n\n   In above commands, each command is run with python 3.10, 3.11, 3.12, and 3.13.\n   If you want to run with a specific version, use `--python` option. For example:\n\n   ```bash\n   uv run nox -s test --python 3.10\n   uv run nox -s lint --python 3.11\n   uv run nox -s mypy --python 3.12\n   ```\n\n   or\n\n   ```bash\n   uv run pytest\n   uv run ruff check src tests\n   uv run mypy src tests\n   ```\n\n6. Commit and push your changes:\n\n   ```bash\n   git add .\n   git commit -m \"Your commit message\"\n   git push origin {your_branch_name}\n   # git push -u origin {your_branch_name} # if you are pushing for the first time\n   ```\n\n7. [Create a pull request](https://github.com/hmasdev/pybizday_utils/compare) to the main repository.\n\n### How to Build\n\n1. Clone the forked repository:\n\n   ```bash\n   git clone https://github.com/hmasdev/pybizday_utils\n   cd pybizday_utils\n   ```\n\n2. (optional) Checkout the branch you want to build:\n\n   ```bash\n   git switch {BRANCH_NAME}\n   # or\n   # git checkout {BRANCH_NAME_OR_COMMIT_HASH}\n   ```\n\n3. Setup the development environment:\n\n   ```bash\n   uv sync --dev\n   ```\n\n4. Build the package:\n\n   ```bash\n   uv build\n   ```\n\n5. See the built package in `dist` directory.\n\n6. (optional) Upload the package to PyPI:\n\n   ```bash\n   uv run twine upload dist/*\n   ```\n\n   Note that `TWINE_USERNAME`, `TWINE_PASSWORD` and `TWINE_REPOSITORY_URL` environment variables must be set to valid values for [pybizday-utils](https://pypi.org/project/pybizday-utils/) project.\n\n### How to Check the Code Performance\n\n`check_performance.py` is provided to check the performance of the library.\n\nThis script measures the elapsed time of `get_n_next_bizday` functions with different values of `n` and `date` given in the command line arguments.\n\n1. Clone the forked repository:\n\n   ```bash\n   git clone https://github.com/hmasdev/pybizday_utils\n   cd pybizday_utils\n   ```\n\n2. (optional) Checkout the branch you want to build:\n\n   ```bash\n   git switch {BRANCH_NAME}\n   # or\n   # git checkout {BRANCH_NAME_OR_COMMIT_HASH}\n   ```\n\n3. Setup the development environment:\n\n   ```bash\n   uv sync --dev\n   ```\n\n4. Run the script:\n\n   ```bash\n   uv run check_performance.py --n 100000 --date 2025-01-01 --n-trials 100\n   ```\n\n   In this case, the command measures the elapsed time to calculate the 100,000-th business day after 2025-01-01, and repeat it 100 times.\n\n## License\n\n[MIT](./LICENSE)\n\n## Author\n\n- [hmasdev](https://github.com/hmasdev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmasdev%2Fpybizday_utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhmasdev%2Fpybizday_utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmasdev%2Fpybizday_utils/lists"}