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.
- purecalendars-0.1.0/LICENSE +21 -0
- purecalendars-0.1.0/PKG-INFO +177 -0
- purecalendars-0.1.0/README.md +137 -0
- purecalendars-0.1.0/pyproject.toml +109 -0
- purecalendars-0.1.0/src/wwdates/__init__.py +16 -0
- purecalendars-0.1.0/src/wwdates/_internal/__init__.py +1 -0
- purecalendars-0.1.0/src/wwdates/_internal/config/__init__.py +1 -0
- purecalendars-0.1.0/src/wwdates/_internal/config/contracts/__init__.py +34 -0
- purecalendars-0.1.0/src/wwdates/_internal/config/contracts/anbima_holidays.py +20 -0
- purecalendars-0.1.0/src/wwdates/_internal/config/contracts/example_source.py +20 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/__init__.py +1 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/br_identifiers.py +257 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/cache/__init__.py +0 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/cache/cache_manager.py +415 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/__init__.py +21 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_abc_calendar.py +70 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_calendar_core.py +147 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_date_formatter.py +225 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_date_manipulation.py +395 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_date_timezone_aware.py +216 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_dates_current.py +69 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/_dates_range_delta.py +421 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/calendars/abc_calendar_operations.py +9 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/dtypes.py +98 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/http_downloader.py +194 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/logs.py +275 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/logs_emitter.py +60 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/parsers/__init__.py +0 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/parsers/dicts.py +45 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/parsers/html.py +47 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/parsers/str.py +129 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/retry.py +191 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/tabular_reader.py +446 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/text.py +79 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/typing/__init__.py +30 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/typing/abc_type_checker.py +16 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/typing/decorators.py +34 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/typing/protocol_type_checker.py +20 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/typing/type_checker.py +87 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/typing/validate.py +306 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/webdriver_tools/__init__.py +0 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/webdriver_tools/playwright_wd.py +1110 -0
- purecalendars-0.1.0/src/wwdates/_internal/utils/zip_extractor.py +257 -0
- purecalendars-0.1.0/src/wwdates/br/__init__.py +8 -0
- purecalendars-0.1.0/src/wwdates/br/anbima.py +237 -0
- purecalendars-0.1.0/src/wwdates/br/b3.py +222 -0
- purecalendars-0.1.0/src/wwdates/br/febraban.py +343 -0
- purecalendars-0.1.0/src/wwdates/us/__init__.py +8 -0
- purecalendars-0.1.0/src/wwdates/us/federal_holidays.py +94 -0
- purecalendars-0.1.0/src/wwdates/us/federal_holidays_web.py +298 -0
- 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
|
+
[](https://www.repostatus.org/#active)
|
|
43
|
+

|
|
44
|
+
[](https://github.com/astral-sh/ruff)
|
|
45
|
+
[](https://mypy-lang.org/)
|
|
46
|
+

|
|
47
|
+

|
|
48
|
+

|
|
49
|
+

|
|
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
|
+
[](https://www.repostatus.org/#active)
|
|
4
|
+

|
|
5
|
+
[](https://github.com/astral-sh/ruff)
|
|
6
|
+
[](https://mypy-lang.org/)
|
|
7
|
+

|
|
8
|
+

|
|
9
|
+

|
|
10
|
+

|
|
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)."""
|