purecalendars 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. purecalendars-0.1.0/LICENSE +21 -0
  2. purecalendars-0.1.0/PKG-INFO +177 -0
  3. purecalendars-0.1.0/README.md +137 -0
  4. purecalendars-0.1.0/pyproject.toml +109 -0
  5. purecalendars-0.1.0/src/wwdates/__init__.py +16 -0
  6. purecalendars-0.1.0/src/wwdates/_internal/__init__.py +1 -0
  7. purecalendars-0.1.0/src/wwdates/_internal/config/__init__.py +1 -0
  8. purecalendars-0.1.0/src/wwdates/_internal/config/contracts/__init__.py +34 -0
  9. purecalendars-0.1.0/src/wwdates/_internal/config/contracts/anbima_holidays.py +20 -0
  10. purecalendars-0.1.0/src/wwdates/_internal/config/contracts/example_source.py +20 -0
  11. purecalendars-0.1.0/src/wwdates/_internal/utils/__init__.py +1 -0
  12. purecalendars-0.1.0/src/wwdates/_internal/utils/br_identifiers.py +257 -0
  13. purecalendars-0.1.0/src/wwdates/_internal/utils/cache/__init__.py +0 -0
  14. purecalendars-0.1.0/src/wwdates/_internal/utils/cache/cache_manager.py +415 -0
  15. purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/__init__.py +21 -0
  16. purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_abc_calendar.py +70 -0
  17. purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_calendar_core.py +147 -0
  18. purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_date_formatter.py +225 -0
  19. purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_date_manipulation.py +395 -0
  20. purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_date_timezone_aware.py +216 -0
  21. purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_dates_current.py +69 -0
  22. purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_dates_range_delta.py +421 -0
  23. purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/abc_calendar_operations.py +9 -0
  24. purecalendars-0.1.0/src/wwdates/_internal/utils/dtypes.py +98 -0
  25. purecalendars-0.1.0/src/wwdates/_internal/utils/http_downloader.py +194 -0
  26. purecalendars-0.1.0/src/wwdates/_internal/utils/logs.py +275 -0
  27. purecalendars-0.1.0/src/wwdates/_internal/utils/logs_emitter.py +60 -0
  28. purecalendars-0.1.0/src/wwdates/_internal/utils/parsers/__init__.py +0 -0
  29. purecalendars-0.1.0/src/wwdates/_internal/utils/parsers/dicts.py +45 -0
  30. purecalendars-0.1.0/src/wwdates/_internal/utils/parsers/html.py +47 -0
  31. purecalendars-0.1.0/src/wwdates/_internal/utils/parsers/str.py +129 -0
  32. purecalendars-0.1.0/src/wwdates/_internal/utils/retry.py +191 -0
  33. purecalendars-0.1.0/src/wwdates/_internal/utils/tabular_reader.py +446 -0
  34. purecalendars-0.1.0/src/wwdates/_internal/utils/text.py +79 -0
  35. purecalendars-0.1.0/src/wwdates/_internal/utils/typing/__init__.py +30 -0
  36. purecalendars-0.1.0/src/wwdates/_internal/utils/typing/abc_type_checker.py +16 -0
  37. purecalendars-0.1.0/src/wwdates/_internal/utils/typing/decorators.py +34 -0
  38. purecalendars-0.1.0/src/wwdates/_internal/utils/typing/protocol_type_checker.py +20 -0
  39. purecalendars-0.1.0/src/wwdates/_internal/utils/typing/type_checker.py +87 -0
  40. purecalendars-0.1.0/src/wwdates/_internal/utils/typing/validate.py +306 -0
  41. purecalendars-0.1.0/src/wwdates/_internal/utils/webdriver_tools/__init__.py +0 -0
  42. purecalendars-0.1.0/src/wwdates/_internal/utils/webdriver_tools/playwright_wd.py +1110 -0
  43. purecalendars-0.1.0/src/wwdates/_internal/utils/zip_extractor.py +257 -0
  44. purecalendars-0.1.0/src/wwdates/br/__init__.py +8 -0
  45. purecalendars-0.1.0/src/wwdates/br/anbima.py +237 -0
  46. purecalendars-0.1.0/src/wwdates/br/b3.py +222 -0
  47. purecalendars-0.1.0/src/wwdates/br/febraban.py +343 -0
  48. purecalendars-0.1.0/src/wwdates/us/__init__.py +8 -0
  49. purecalendars-0.1.0/src/wwdates/us/federal_holidays.py +94 -0
  50. purecalendars-0.1.0/src/wwdates/us/federal_holidays_web.py +298 -0
  51. purecalendars-0.1.0/src/wwdates/us/nasdaq.py +209 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 guilhermegor
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,177 @@
1
+ Metadata-Version: 2.4
2
+ Name: purecalendars
3
+ Version: 0.1.0
4
+ Summary: Global calendar system. Python package.
5
+ License: MIT
6
+ License-File: LICENSE
7
+ Keywords: wwdates,python,library
8
+ Author: guilhermegor
9
+ Requires-Python: >=3.10,<4.0
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Programming Language :: Python :: 3.15
21
+ Classifier: Topic :: Software Development :: Libraries
22
+ Provides-Extra: web
23
+ Requires-Dist: businesstimedelta (>=1.0.1,<2.0.0)
24
+ Requires-Dist: holidays (>=0.99,<0.100)
25
+ Requires-Dist: lxml (>=6.1.1,<7.0.0)
26
+ Requires-Dist: openpyxl (>=3.1.0)
27
+ Requires-Dist: pandas (>=2.1.0)
28
+ Requires-Dist: playwright (>=1.61.0,<2.0.0) ; extra == "web"
29
+ Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
30
+ Requires-Dist: requests (>=2.34.2,<3.0.0)
31
+ Requires-Dist: tzdata (>=2026.2,<2027.0)
32
+ Requires-Dist: xlrd (>=2.0.2,<3.0.0)
33
+ Project-URL: Bug Reports, https://github.com/guilhermegor/wwdates/issues
34
+ Project-URL: Documentation, https://guilhermegor.github.io/wwdates/
35
+ Project-URL: Homepage, https://guilhermegor.github.io/wwdates/
36
+ Project-URL: Repository, https://github.com/guilhermegor/wwdates
37
+ Project-URL: Source, https://github.com/guilhermegor/wwdates
38
+ Description-Content-Type: text/markdown
39
+
40
+ # wwdates <img src="assets/logo_wwdates_no_description.png" align="right" width="200" style="border-radius: 15px;" alt="wwdates">
41
+
42
+ [![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
43
+ ![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)
44
+ [![Linting](https://img.shields.io/badge/linting-ruff_|_codespell-blue)](https://github.com/astral-sh/ruff)
45
+ [![Type-checked: mypy](https://img.shields.io/badge/type--checked-mypy-blue)](https://mypy-lang.org/)
46
+ ![Test Coverage](./coverage.svg)
47
+ ![License](https://img.shields.io/badge/license-MIT-green.svg)
48
+ ![Open Issues](https://img.shields.io/github/issues/guilhermegor/wwdates)
49
+ ![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-darkgreen.svg)
50
+
51
+ Global calendar system. Python package.
52
+
53
+ `wwdates` fetches official holiday calendars for Brazil (ANBIMA, FEBRABAN, B3) and the United
54
+ States (Nasdaq, Federal Holidays), then layers a rich set of working-day / date helpers on top —
55
+ `is_working_day`, `add_working_days`, `working_days_range`, `delta_working_days`, timezone-aware
56
+ conversions, and more. Fetched calendars are cached locally so repeated calls stay fast and
57
+ offline-friendly.
58
+
59
+ 📖 **Full documentation:** <https://guilhermegor.github.io/wwdates/>
60
+
61
+ ## ✨ Key Features
62
+
63
+ ### 🗓️ Holiday providers
64
+
65
+ One class per calendar source; all share the same date-operations surface — they differ only in
66
+ **which** holidays they load.
67
+
68
+ | Provider | Import | Holidays |
69
+ | --------------------------- | --------------------------------- | --------------------------------------------- |
70
+ | `DatesBRAnbima` | `wwdates.br.anbima` | 🇧🇷 ANBIMA national holidays |
71
+ | `DatesBRFebraban` | `wwdates.br.febraban` | 🇧🇷 FEBRABAN bank holidays |
72
+ | `DatesBRB3` | `wwdates.br.b3` | 🇧🇷 ANBIMA + B3 exchange non-trading days |
73
+ | `DatesUSNasdaq` | `wwdates.us.nasdaq` | 🇺🇸 Nasdaq market closures |
74
+ | `DatesUSFederalHolidays` | `wwdates.us.federal_holidays` | 🇺🇸 US federal holidays (offline, recommended) |
75
+ | `DatesUSFederalHolidaysWeb` | `wwdates.us.federal_holidays_web` | 🇺🇸 US federal holidays via live scrape |
76
+
77
+ ### ⚙️ Shared calendar operations
78
+
79
+ Every provider inherits the full surface: working-day predicates (`is_working_day`, `is_holiday`,
80
+ `is_weekend`), business-day arithmetic (`add_working_days`, `nearest_working_day`,
81
+ `get_nth_weekday_month`), ranges & deltas (`working_days_range`, `delta_working_days`,
82
+ `delta_working_hours`), timezone/timestamp conversions, and locale-aware formatting. See the
83
+ [API Reference](https://guilhermegor.github.io/wwdates/api/) for the complete list.
84
+
85
+ ## 🚀 Getting Started
86
+
87
+ ### Prerequisites
88
+
89
+ - Python 3.10+
90
+ - Poetry (recommended)
91
+
92
+ ### Installation
93
+
94
+ ```bash
95
+ pip install wwdates
96
+ ```
97
+
98
+ Or with Poetry:
99
+
100
+ ```bash
101
+ poetry add wwdates
102
+ ```
103
+
104
+ Everything works offline after install — **no browser needed**. The recommended
105
+ `DatesUSFederalHolidays` computes federal holidays locally.
106
+
107
+ ### Optional: the browser-scrape provider (`[web]` extra)
108
+
109
+ **Only** the `DatesUSFederalHolidaysWeb` provider needs a browser — it scrapes
110
+ federalholidays.net with Playwright, which is **not** installed by the base package. It is
111
+ **vital only if you specifically want that provider's live-scraped dates**; otherwise skip this
112
+ entirely and use the offline `DatesUSFederalHolidays`.
113
+
114
+ To enable it, install the optional `web` extra (note the brackets — quote them so the shell does
115
+ not glob), then fetch the browser binary:
116
+
117
+ ```bash
118
+ pip install "wwdates[web]" # adds Playwright
119
+ playwright install chromium # one-time browser download (pip cannot do this step)
120
+ ```
121
+
122
+ Without both steps, constructing/using `DatesUSFederalHolidaysWeb` raises a clear `ImportError`
123
+ telling you to run them.
124
+
125
+ ### Quick start
126
+
127
+ ```python
128
+ from datetime import date
129
+
130
+ from wwdates.br.b3 import DatesBRB3
131
+
132
+ cls_cal = DatesBRB3()
133
+ cls_cal.is_working_day(date(2024, 12, 25)) # False — Christmas
134
+ cls_cal.add_working_days(date(2024, 12, 24), 3) # skips holidays + weekends
135
+ cls_cal.holidays() # [(name, date), ...]
136
+ ```
137
+
138
+ `DatesBRB3` here is just an example — the same methods work on every provider; only the loaded
139
+ holiday set differs. More recipes in the
140
+ [Examples](https://guilhermegor.github.io/wwdates/examples/) guide.
141
+
142
+ ## 📚 Documentation
143
+
144
+ - [Usage](https://guilhermegor.github.io/wwdates/usage/) — install, providers, basics
145
+ - [Examples](https://guilhermegor.github.io/wwdates/examples/) — task-oriented recipes
146
+ - [API Reference](https://guilhermegor.github.io/wwdates/api/) — every class and method
147
+ - [FAQ](https://guilhermegor.github.io/wwdates/faq/) — common questions & troubleshooting
148
+ - [Contributing](https://guilhermegor.github.io/wwdates/contributing/) — dev setup, tests, releasing
149
+ - [Changelog](https://guilhermegor.github.io/wwdates/changelog/) — release history
150
+
151
+ ## 🛠️ Development
152
+
153
+ ```bash
154
+ git clone https://github.com/guilhermegor/wwdates.git
155
+ cd wwdates
156
+ make init # or: bash tasks.sh init (venv + deps + pre-commit hooks)
157
+ make unit_tests # run the test suite
158
+ make install_dist_locally # build the wheel and smoke-import it
159
+ ```
160
+
161
+ See [Contributing](https://guilhermegor.github.io/wwdates/contributing/) for the full branch/PR
162
+ workflow and CI gate.
163
+
164
+ ## 👨‍💻 Authors
165
+
166
+ - guilhermegor — [GitHub](https://github.com/guilhermegor)
167
+
168
+ ## 📜 License
169
+
170
+ This project is licensed under the **MIT** License — see [`LICENSE`](LICENSE) for details.
171
+
172
+ ## 🔗 Useful Links
173
+
174
+ - [Documentation](https://guilhermegor.github.io/wwdates/)
175
+ - [GitHub Repository](https://github.com/guilhermegor/wwdates)
176
+ - [Issue Tracker](https://github.com/guilhermegor/wwdates/issues)
177
+
@@ -0,0 +1,137 @@
1
+ # wwdates <img src="assets/logo_wwdates_no_description.png" align="right" width="200" style="border-radius: 15px;" alt="wwdates">
2
+
3
+ [![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
4
+ ![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)
5
+ [![Linting](https://img.shields.io/badge/linting-ruff_|_codespell-blue)](https://github.com/astral-sh/ruff)
6
+ [![Type-checked: mypy](https://img.shields.io/badge/type--checked-mypy-blue)](https://mypy-lang.org/)
7
+ ![Test Coverage](./coverage.svg)
8
+ ![License](https://img.shields.io/badge/license-MIT-green.svg)
9
+ ![Open Issues](https://img.shields.io/github/issues/guilhermegor/wwdates)
10
+ ![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-darkgreen.svg)
11
+
12
+ Global calendar system. Python package.
13
+
14
+ `wwdates` fetches official holiday calendars for Brazil (ANBIMA, FEBRABAN, B3) and the United
15
+ States (Nasdaq, Federal Holidays), then layers a rich set of working-day / date helpers on top —
16
+ `is_working_day`, `add_working_days`, `working_days_range`, `delta_working_days`, timezone-aware
17
+ conversions, and more. Fetched calendars are cached locally so repeated calls stay fast and
18
+ offline-friendly.
19
+
20
+ 📖 **Full documentation:** <https://guilhermegor.github.io/wwdates/>
21
+
22
+ ## ✨ Key Features
23
+
24
+ ### 🗓️ Holiday providers
25
+
26
+ One class per calendar source; all share the same date-operations surface — they differ only in
27
+ **which** holidays they load.
28
+
29
+ | Provider | Import | Holidays |
30
+ | --------------------------- | --------------------------------- | --------------------------------------------- |
31
+ | `DatesBRAnbima` | `wwdates.br.anbima` | 🇧🇷 ANBIMA national holidays |
32
+ | `DatesBRFebraban` | `wwdates.br.febraban` | 🇧🇷 FEBRABAN bank holidays |
33
+ | `DatesBRB3` | `wwdates.br.b3` | 🇧🇷 ANBIMA + B3 exchange non-trading days |
34
+ | `DatesUSNasdaq` | `wwdates.us.nasdaq` | 🇺🇸 Nasdaq market closures |
35
+ | `DatesUSFederalHolidays` | `wwdates.us.federal_holidays` | 🇺🇸 US federal holidays (offline, recommended) |
36
+ | `DatesUSFederalHolidaysWeb` | `wwdates.us.federal_holidays_web` | 🇺🇸 US federal holidays via live scrape |
37
+
38
+ ### ⚙️ Shared calendar operations
39
+
40
+ Every provider inherits the full surface: working-day predicates (`is_working_day`, `is_holiday`,
41
+ `is_weekend`), business-day arithmetic (`add_working_days`, `nearest_working_day`,
42
+ `get_nth_weekday_month`), ranges & deltas (`working_days_range`, `delta_working_days`,
43
+ `delta_working_hours`), timezone/timestamp conversions, and locale-aware formatting. See the
44
+ [API Reference](https://guilhermegor.github.io/wwdates/api/) for the complete list.
45
+
46
+ ## 🚀 Getting Started
47
+
48
+ ### Prerequisites
49
+
50
+ - Python 3.10+
51
+ - Poetry (recommended)
52
+
53
+ ### Installation
54
+
55
+ ```bash
56
+ pip install wwdates
57
+ ```
58
+
59
+ Or with Poetry:
60
+
61
+ ```bash
62
+ poetry add wwdates
63
+ ```
64
+
65
+ Everything works offline after install — **no browser needed**. The recommended
66
+ `DatesUSFederalHolidays` computes federal holidays locally.
67
+
68
+ ### Optional: the browser-scrape provider (`[web]` extra)
69
+
70
+ **Only** the `DatesUSFederalHolidaysWeb` provider needs a browser — it scrapes
71
+ federalholidays.net with Playwright, which is **not** installed by the base package. It is
72
+ **vital only if you specifically want that provider's live-scraped dates**; otherwise skip this
73
+ entirely and use the offline `DatesUSFederalHolidays`.
74
+
75
+ To enable it, install the optional `web` extra (note the brackets — quote them so the shell does
76
+ not glob), then fetch the browser binary:
77
+
78
+ ```bash
79
+ pip install "wwdates[web]" # adds Playwright
80
+ playwright install chromium # one-time browser download (pip cannot do this step)
81
+ ```
82
+
83
+ Without both steps, constructing/using `DatesUSFederalHolidaysWeb` raises a clear `ImportError`
84
+ telling you to run them.
85
+
86
+ ### Quick start
87
+
88
+ ```python
89
+ from datetime import date
90
+
91
+ from wwdates.br.b3 import DatesBRB3
92
+
93
+ cls_cal = DatesBRB3()
94
+ cls_cal.is_working_day(date(2024, 12, 25)) # False — Christmas
95
+ cls_cal.add_working_days(date(2024, 12, 24), 3) # skips holidays + weekends
96
+ cls_cal.holidays() # [(name, date), ...]
97
+ ```
98
+
99
+ `DatesBRB3` here is just an example — the same methods work on every provider; only the loaded
100
+ holiday set differs. More recipes in the
101
+ [Examples](https://guilhermegor.github.io/wwdates/examples/) guide.
102
+
103
+ ## 📚 Documentation
104
+
105
+ - [Usage](https://guilhermegor.github.io/wwdates/usage/) — install, providers, basics
106
+ - [Examples](https://guilhermegor.github.io/wwdates/examples/) — task-oriented recipes
107
+ - [API Reference](https://guilhermegor.github.io/wwdates/api/) — every class and method
108
+ - [FAQ](https://guilhermegor.github.io/wwdates/faq/) — common questions & troubleshooting
109
+ - [Contributing](https://guilhermegor.github.io/wwdates/contributing/) — dev setup, tests, releasing
110
+ - [Changelog](https://guilhermegor.github.io/wwdates/changelog/) — release history
111
+
112
+ ## 🛠️ Development
113
+
114
+ ```bash
115
+ git clone https://github.com/guilhermegor/wwdates.git
116
+ cd wwdates
117
+ make init # or: bash tasks.sh init (venv + deps + pre-commit hooks)
118
+ make unit_tests # run the test suite
119
+ make install_dist_locally # build the wheel and smoke-import it
120
+ ```
121
+
122
+ See [Contributing](https://guilhermegor.github.io/wwdates/contributing/) for the full branch/PR
123
+ workflow and CI gate.
124
+
125
+ ## 👨‍💻 Authors
126
+
127
+ - guilhermegor — [GitHub](https://github.com/guilhermegor)
128
+
129
+ ## 📜 License
130
+
131
+ This project is licensed under the **MIT** License — see [`LICENSE`](LICENSE) for details.
132
+
133
+ ## 🔗 Useful Links
134
+
135
+ - [Documentation](https://guilhermegor.github.io/wwdates/)
136
+ - [GitHub Repository](https://github.com/guilhermegor/wwdates)
137
+ - [Issue Tracker](https://github.com/guilhermegor/wwdates/issues)
@@ -0,0 +1,109 @@
1
+ [tool.poetry]
2
+ name = "purecalendars"
3
+ # Placeholder only — the real version is derived from the git tag at build time by
4
+ # poetry-dynamic-versioning (see [tool.poetry-dynamic-versioning]). Do not bump this by hand;
5
+ # releases are cut by tagging via the CI release workflows.
6
+ version = "0.1.0"
7
+ description = "Global calendar system. Python package."
8
+ authors = ["guilhermegor"]
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ homepage = "https://guilhermegor.github.io/wwdates/"
12
+ documentation = "https://guilhermegor.github.io/wwdates/"
13
+ repository = "https://github.com/guilhermegor/wwdates"
14
+ keywords = ["wwdates", "python", "library"]
15
+ packages = [{ include = "wwdates", from = "src" }]
16
+ # Keep internal dev docs out of the distributed wheel/sdist.
17
+ exclude = ["src/**/CLAUDE.md"]
18
+ package-mode = true
19
+ classifiers = [
20
+ "Programming Language :: Python :: 3",
21
+ "Operating System :: OS Independent",
22
+ "License :: OSI Approved :: MIT License",
23
+ "Development Status :: 3 - Alpha",
24
+ "Intended Audience :: Developers",
25
+ "Topic :: Software Development :: Libraries",
26
+ ]
27
+
28
+ [tool.poetry.urls]
29
+ "Bug Reports" = "https://github.com/guilhermegor/wwdates/issues"
30
+ "Source" = "https://github.com/guilhermegor/wwdates"
31
+ "Documentation" = "https://guilhermegor.github.io/wwdates/"
32
+
33
+ [tool.poetry.dependencies]
34
+ python = ">=3.10,<4.0"
35
+ # Required by the private _internal helpers (dtypes / tabular_reader / config.contracts).
36
+ pandas = ">=2.1.0"
37
+ openpyxl = ">=3.1.0"
38
+ requests = "^2.34.2"
39
+ businesstimedelta = "^1.0.1"
40
+ python-dateutil = "^2.9.0.post0"
41
+ xlrd = "^2.0.2"
42
+ lxml = "^6.1.1"
43
+ tzdata = "^2026.2"
44
+ holidays = "^0.99"
45
+ # Optional — only DatesUSFederalHolidaysWeb (the live-scrape provider) needs a browser.
46
+ # Installed via the `web` extra: pip install "wwdates[web]".
47
+ playwright = { version = "^1.61.0", optional = true }
48
+
49
+ [tool.poetry.extras]
50
+ # `pip install "wwdates[web]"` adds Playwright for the live-scrape DatesUSFederalHolidaysWeb
51
+ # provider. After installing, run `playwright install chromium` once to fetch the browser.
52
+ web = ["playwright"]
53
+
54
+ [tool.commitizen]
55
+ # Conventional-commit driven changelog. The version comes from the git tag
56
+ # (poetry-dynamic-versioning); `cz changelog` groups commits by tag. Releases are cut by the CI
57
+ # release workflows (tag -> build -> publish), not by a hand-run bump.
58
+ name = "cz_conventional_commits"
59
+ version_provider = "poetry"
60
+ tag_format = "v$version"
61
+ update_changelog_on_bump = true
62
+
63
+ [tool.poetry.group.dev.dependencies]
64
+ pre-commit = ">=4.1.0"
65
+ pretty-errors = ">=1.2.25"
66
+ commitizen = ">=4.4.1"
67
+ poetry-plugin-export = ">=1.8"
68
+ # Build + publish tooling for the PyPI / Test-PyPI release workflows (twine is the
69
+ # publish fallback when `poetry publish` is unavailable).
70
+ build = ">=1.2.2"
71
+ twine = ">=6.1.0"
72
+ # Pinned to the ruff-pre-commit hook minor (.pre-commit-config.yaml) so `make
73
+ # lint` and the hook never disagree on formatting/lints.
74
+ ruff = ">=0.11.13,<0.12"
75
+ codespell = ">=2.4.1"
76
+ pydocstyle = ">=6.3.0"
77
+ pytest = ">=8.0.0"
78
+ pytest-cov = ">=6.0.0"
79
+ coverage = ">=7.6.0"
80
+ # genbadge replaces the abandoned coverage-badge (it imported the removed
81
+ # pkg_resources and breaks on setuptools >= 81).
82
+ genbadge = {extras = ["coverage"], version = ">=1.1.0"}
83
+ # Static type-checker + non-Python lint gates (mirrored in .pre-commit-config and
84
+ # `make lint`). shellcheck + shfmt are pip dev-deps (shellcheck-py/shfmt-py); lint_shell.sh resolves them via poetry run, falls back to a system binary, then skips.
85
+ mypy = ">=1.8.0"
86
+ sqlfluff = ">=3.0.0"
87
+ yamllint = ">=1.35.0"
88
+ shfmt-py = ">=3.7.0"
89
+ shellcheck-py = ">=0.10.0"
90
+ pytest-mock = "^3.15.1"
91
+
92
+ [tool.poetry.group.docs.dependencies]
93
+ mkdocs = ">=1.6.0"
94
+ mkdocs-material = ">=9.5.0"
95
+ pymdown-extensions = ">=10.0"
96
+
97
+ [tool.poetry-dynamic-versioning]
98
+ # The published version is derived from the latest git tag matching `v$version` (e.g. v0.2.0).
99
+ # On an exact tag the build is clean (0.2.0); off-tag builds get a PEP 440 dev version. CI stamps
100
+ # a release by tagging the commit before build; Test PyPI passes POETRY_DYNAMIC_VERSIONING_BYPASS
101
+ # to build a specific version without creating a tag. Requires `python -m build` (a PEP 517
102
+ # frontend) rather than `poetry build`, so the backend below is honoured.
103
+ enable = false
104
+ vcs = "git"
105
+ style = "pep440"
106
+
107
+ [build-system]
108
+ requires = ["poetry-core>=1.7.0", "poetry-dynamic-versioning>=1.4.0,<2.0.0"]
109
+ build-backend = "poetry_dynamic_versioning.backend"
@@ -0,0 +1,16 @@
1
+ """wwdates — worldwide holiday calendars and date operations.
2
+
3
+ Import the country subpackages for the concrete providers, e.g.
4
+ ``from wwdates.br.b3 import DatesBRB3`` or ``from wwdates.us.nasdaq import DatesUSNasdaq``.
5
+ """
6
+
7
+ from importlib.metadata import PackageNotFoundError, version
8
+
9
+
10
+ try:
11
+ __version__ = version("purecalendars")
12
+ except PackageNotFoundError: # pragma: no cover - source tree without an installed dist
13
+ __version__ = "0.0.0"
14
+
15
+
16
+ __all__ = ["__version__"]
@@ -0,0 +1 @@
1
+ """Private internals of the wwdates package (not a public API)."""
@@ -0,0 +1 @@
1
+ """Private configuration internals (data contracts) of wwdates."""
@@ -0,0 +1,34 @@
1
+ """Data contracts for the project's input files (config layer).
2
+
3
+ A contract is **declarative configuration** of an input's expected shape — which columns a
4
+ source must carry, which must hold valid CNPJs — *not* data access, so contracts live in
5
+ ``config`` beside the other declarative config (``inputs.yaml``, ``connection_db``), imported
6
+ by the model loaders and the controller boundary.
7
+
8
+ Convention: **one file per source** under this package (``cadastro.py``, ``orders.py``, …),
9
+ each defining a single ``FileContract`` instance; this aggregator re-exports them (plus the
10
+ machinery from ``utils.tabular_reader``) so callers import from one place:
11
+ ``from config.contracts import EXAMPLE_SOURCE, find_file_problems``.
12
+
13
+ ``EXAMPLE_SOURCE`` is a reference instance — copy ``example_source.py`` per real source and
14
+ delete the example once your own contracts exist.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ from wwdates._internal.config.contracts.anbima_holidays import ANBIMA_HOLIDAYS
20
+ from wwdates._internal.config.contracts.example_source import EXAMPLE_SOURCE
21
+ from wwdates._internal.utils.tabular_reader import (
22
+ ContractError,
23
+ FileContract,
24
+ find_file_problems,
25
+ )
26
+
27
+
28
+ __all__ = [
29
+ "ANBIMA_HOLIDAYS",
30
+ "EXAMPLE_SOURCE",
31
+ "ContractError",
32
+ "FileContract",
33
+ "find_file_problems",
34
+ ]
@@ -0,0 +1,20 @@
1
+ """Data contract for the ANBIMA national-holidays workbook.
2
+
3
+ The ANBIMA ``.xls`` is headerless with a title banner on the first row, so it is read
4
+ ``skiprows=1`` with the three columns assigned positionally (``DATE``, ``WEEKDAY``, ``NAME``)
5
+ via ``tabular_reader.read_table``; this contract asserts those columns are present before the
6
+ provider transforms them.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from wwdates._internal.utils.tabular_reader import FileContract
12
+
13
+
14
+ # str_name, str_source_key, tuple_required, tuple_cnpj_cols (none — holidays carry no CNPJ).
15
+ ANBIMA_HOLIDAYS = FileContract(
16
+ "ANBIMA National Holidays",
17
+ "anbima_holidays",
18
+ ("DATE", "WEEKDAY", "NAME"),
19
+ (),
20
+ )
@@ -0,0 +1,20 @@
1
+ """Reference data contract — copy this per real input source, then delete the example.
2
+
3
+ Declares the columns the file must carry (``tuple_required``) and the columns that must hold
4
+ at least one valid CNPJ (``tuple_cnpj_cols``). The model/controller passes this instance to
5
+ ``utils.tabular_reader.read_table`` / ``read_query``, which raises ``ContractError`` on any
6
+ violation before types are applied.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from wwdates._internal.utils.tabular_reader import FileContract
12
+
13
+
14
+ # str_name (human label), str_source_key (routes notifications), tuple_required, tuple_cnpj_cols.
15
+ EXAMPLE_SOURCE = FileContract(
16
+ "Example Source",
17
+ "example_source",
18
+ ("code", "amount"),
19
+ (),
20
+ )
@@ -0,0 +1 @@
1
+ """Shared, project-agnostic utility helpers (copied into every Python skeleton)."""