{"id":20290619,"url":"https://github.com/gocardless/business-python","last_synced_at":"2025-07-01T03:06:40.143Z","repository":{"id":38340614,"uuid":"257231531","full_name":"gocardless/business-python","owner":"gocardless","description":"Python business day calculations","archived":false,"fork":false,"pushed_at":"2024-06-05T14:39:24.000Z","size":345,"stargazers_count":16,"open_issues_count":11,"forks_count":5,"subscribers_count":51,"default_branch":"master","last_synced_at":"2025-06-15T12:16:02.046Z","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/gocardless.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-04-20T09:24:43.000Z","updated_at":"2025-04-09T10:15:51.000Z","dependencies_parsed_at":"2024-06-05T16:38:04.814Z","dependency_job_id":"8dd79649-e9da-4e17-875e-7c24ebb01823","html_url":"https://github.com/gocardless/business-python","commit_stats":{"total_commits":42,"total_committers":5,"mean_commits":8.4,"dds":0.5714285714285714,"last_synced_commit":"d436c45f3c90da0d84c009a5d1f1ca60a92c3498"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/gocardless/business-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fbusiness-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fbusiness-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fbusiness-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fbusiness-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gocardless","download_url":"https://codeload.github.com/gocardless/business-python/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fbusiness-python/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262887188,"owners_count":23379768,"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":"2024-11-14T15:08:29.757Z","updated_at":"2025-07-01T03:06:40.118Z","avatar_url":"https://github.com/gocardless.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Business (Python)\n\n[![circleci-badge](https://circleci.com/gh/gocardless/business-python.svg?style=shield)](https://app.circleci.com/pipelines/github/gocardless/business-python) [![pypi-badge](https://badge.fury.io/py/business-python.svg)](https://badge.fury.io/py/business-python)\n\nDate calculations based on business calendars. (Python 3.8+)\n\nPython implementation of https://github.com/gocardless/business\n\n## Documentation\n\nTo get business, simply:\n\n```bash\n$ pip install business-python\n```\n\n## Version 2.1.0 breaking changes\n\nIn version 2.1.0 we have dropped support for End-of-Life Python version 3.6 and 3.7. Last release supporting these versions is [v2.0.3](https://github.com/gocardless/business-python/tree/v2.0.3).\n\n## Version 2.0.0 breaking changes\n\nIn version 2.0.0 we have removed the bundled calendars. If you still need these they are available on [v1.0.1](https://github.com/gocardless/business-python/tree/74fe7e4068e0f16b68e7478f8b5ca1cc52f9a7d0/business/data).\n\n### Migration\n\n- Download/create calendars to a directory within your project eg: `lib/calendars`\n- Change your code to include the `load_path` for your calendars\n- Continue using `.load(\"my_calendar\")` as usual\n\n```python\n# lib/calendars contains yml files\nCalendar.load_paths = ['lib/calendars']\ncalendar = Calendar.load(\"my_calendar\")\n```\n\n### Getting started\n\nGet started with business by creating an instance of the calendar class, passing in a hash that specifies which days of the week are considered working days, and which days are holidays.\n\n```python\nfrom business.calendar import Calendar\n\ncalendar = Calendar(\n  working_days=[\"monday\", \"tuesday\", \"wednesday\", \"thursday\", \"friday\"],\n  # array items are either parseable date strings, or real datetime.date objects\n  holidays=[\"January 1st, 2020\", \"April 10th, 2020\"],\n  extra_working_dates=[],\n)\n```\n\n`extra_working_dates` key makes the calendar to consider a weekend day as a working day.\n\nIf `working_days` is missing, then common default is used (mon-fri).\nIf `holidays` is missing, \"no holidays\" assumed.\nIf `extra_working_dates` is missing, then no changes in `working_days` will happen.\n\nElements of `holidays` and `extra_working_dates` may be either strings that `Calendar.parse_date()` can understand, or YYYY-MM-DD (which is considered as a Date by Python YAML itself).\n\n#### Calendar YAML file example\n\n```yaml\n# lib/calendars/my_calendar.yml\nworking_days:\n  - Monday\n  - Sunday\nholidays:\n  - 2017-01-08 # Same as January 8th, 2017\nextra_working_dates:\n  - 2020-12-26 # Will consider 26 Dec 2020 (A Saturday), a working day\n```\n\nThe `load_cache` method allows a thread safe way to avoid reloading the same calendar multiple times, and provides a performant way to dynamically load calendars for different requests.\n\n#### Using business-python\n\nDefine your calendars in a folder eg: `lib/calendars` and set this directory on `Calendar.load_paths=`\n\n```python\nCalendar.load_paths = ['lib/calendars']\ncalendar = Calendar.load_cache(\"my_calendar\")\n```\n\n### Input data types\n\nThe `parse_date` method is used to process the input date(s) in each method and return a `datetime.date` object.\n\n```python\nCalendar.parse_date(\"2019-01-01\")\n# =\u003e datetime.date(2019, 1, 1)\n```\n\nSupported data types are:\n\n- `datetime.date`\n- `datetime.datetime`\n- `pandas.Timestamp` (treated as `datetime.datetime`)\n- date string parseable by [`dateutil.parser.parse`](https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.parse)\n\n`numpy.datetime64` is not supported, but can be converted to `datetime.date`:\n\n```python\nnumpy.datetime64('2014-06-01T23:00:05.453000000').astype('M8[D]').astype('O')\n# =\u003e  datetime.date(2014, 6, 1)\n```\n\n### Checking for business days\n\nTo check whether a given date is a business day (falls on one of the specified working days or extra working dates, and is not a holiday), use the `is_business_day` method on `Calendar`.\n\n```python\ncalendar.is_business_day(\"Monday, 8 June 2020\")\n# =\u003e true\ncalendar.is_business_day(\"Sunday, 7 June 2020\")\n# =\u003e false\n```\n\n### Business day arithmetic\n\n\u003e For our purposes, date-based calculations are sufficient. Supporting time-based calculations as well makes the code significantly more complex. We chose to avoid this extra complexity by sticking solely to date-based mathematics.\n\nThe `add_business_days` method is used to perform business day arithmetic on dates.\n\n```python\ninput_date = Calendar.parse_date(\"Thursday, 12 June 2014\")\ncalendar.add_business_days(input_date, 4).strftime(\"%A, %d %B %Y\")\n# =\u003e \"Wednesday, 18 June 2014\"\ncalendar.add_business_days(input_date, -4).strftime(\"%A, %d %B %Y\")\n# =\u003e \"Friday, 06 June 2014\"\n```\n\nThe `roll_forward` and `roll_backward` methods snap a date to a nearby business day. If provided with a business day, they will return that date. Otherwise, they will advance (forward for `roll_forward` and backward for `roll_backward`) until a business day is found.\n\n```python\ninput_date = Calendar.parse_date(\"Saturday, 14 June 2014\")\ncalendar.roll_forward(input_date).strftime(\"%A, %d %B %Y\")\n# =\u003e \"Monday, 16 June 2014\"\ncalendar.roll_backward(input_date).strftime(\"%A, %d %B %Y\")\n# =\u003e \"Friday, 13 June 2014\"\n```\n\nIn contrast, the `next_business_day` and `previous_business_day` methods will always move to a next or previous date until a business day is found, regardless if the input provided is a business day.\n\n```python\ninput_date = Calendar.parse_date(\"Monday, 9 June 2014\")\ncalendar.roll_forward(input_date).strftime(\"%A, %d %B %Y\")\n# =\u003e \"Monday, 09 June 2014\"\ncalendar.next_business_day(input_date).strftime(\"%A, %d %B %Y\")\n# =\u003e \"Tuesday, 10 June 2014\"\ncalendar.previous_business_day(input_date).strftime(\"%A, %d %B %Y\")\n# =\u003e \"Friday, 06 June 2014\"\n```\n\nTo count the number of business days between two dates, pass the dates to `business_days_between`. This method counts from start of the first date to start of the second date. So, assuming no holidays, there would be two business days between a Monday and a Wednesday.\n\n```python\nfrom datetime import timedelta\n\ninput_date = Calendar.parse_date(\"Saturday, 14 June 2014\")\ncalendar.business_days_between(input_date, input_date + timedelta(days=7))\n# =\u003e 5\n```\n\nThe `get_business_day_of_month` method return the running total of business days for a given date in that month. This method counts the number of business days from the start of the first day of the month to the given input date.\n\n```python\ninput_date = Calendar.parse_date(\"Thursday, 12 June 2014\")\ncalendar.get_business_day_of_month(input_date)\n# =\u003e 9\n```\n\n## License \u0026 Contributing\n\n- This is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n- Bug reports and pull requests are welcome on GitHub at https://github.com/gocardless/business-python.\n\nGoCardless ♥ open source. If you do too, come [join us](https://gocardless.com/about/jobs).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocardless%2Fbusiness-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgocardless%2Fbusiness-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocardless%2Fbusiness-python/lists"}