black-beard-calendarium 0.2.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.
- black_beard_calendarium-0.2.0/LICENSE +21 -0
- black_beard_calendarium-0.2.0/PKG-INFO +413 -0
- black_beard_calendarium-0.2.0/README.md +372 -0
- black_beard_calendarium-0.2.0/pyproject.toml +43 -0
- black_beard_calendarium-0.2.0/setup.cfg +4 -0
- black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/PKG-INFO +413 -0
- black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/SOURCES.txt +143 -0
- black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/dependency_links.txt +1 -0
- black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/entry_points.txt +2 -0
- black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/requires.txt +3 -0
- black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/top_level.txt +1 -0
- black_beard_calendarium-0.2.0/src/calendarium/__init__.py +83 -0
- black_beard_calendarium-0.2.0/src/calendarium/calendars.py +438 -0
- black_beard_calendarium-0.2.0/src/calendarium/chinese.py +269 -0
- black_beard_calendarium-0.2.0/src/calendarium/cli.py +193 -0
- black_beard_calendarium-0.2.0/src/calendarium/core.py +406 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Albania.json +127 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Algeria.json +107 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Andorra.json +172 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Angola.json +154 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Argentina.json +228 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Armenia.json +158 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Australia.json +82 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Austria.json +144 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Azerbaijan.json +172 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Bahrain.json +137 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Belarus.json +82 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Belgium.json +137 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Bolivia.json +150 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Bosnia_and_Herzegovina.json +143 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Brazil.json +175 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Brunei.json +157 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Bulgaria.json +119 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Canada.json +117 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Chile.json +213 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_China.json +113 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Colombia.json +252 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Congo_Democratic_Republic_of.json +117 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Costa_Rica.json +117 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Croatia.json +130 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Cyprus.json +134 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Czechia.json +116 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Denmark.json +187 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Dominican_Republic.json +168 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Ecuador.json +130 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Egypt.json +164 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_El_Salvador.json +109 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Equatorial_Guinea.json +129 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Estonia.json +102 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Finland.json +217 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_France.json +197 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Georgia.json +130 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Germany.json +162 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Greece.json +109 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Guatemala.json +171 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Holy_See_Vatican_City.json +117 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Honduras.json +147 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Hong_Kong_S_A_R.json +150 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Hungary.json +166 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Iceland.json +129 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_India.json +32 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Iran.json +252 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Iraq.json +181 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Ireland.json +95 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Israel.json +84 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Italy.json +109 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Jamaica.json +87 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Japan.json +151 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Jordan.json +137 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Kazakhstan.json +132 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Kenya.json +99 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Korea.json +140 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Kuwait.json +130 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Latvia.json +185 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Lebanon.json +170 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Liechtenstein.json +203 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Lithuania.json +208 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Luxembourg.json +123 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Macao_S_A_R.json +156 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Macedonia_FYRO.json +99 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Malaysia.json +153 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Malta.json +130 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Mexico.json +154 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Moldova.json +109 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Monaco.json +139 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Montenegro.json +92 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Morocco.json +152 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Netherlands.json +171 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_New_Zealand.json +104 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Nicaragua.json +116 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Nigeria.json +132 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Norway.json +182 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Oman.json +130 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Pakistan.json +144 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Panama.json +176 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Paraguay.json +159 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Peru.json +116 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Philippines.json +168 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Poland.json +192 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Portugal.json +130 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Puerto_Rico.json +146 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Qatar.json +85 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Romania.json +221 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Russia.json +130 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_San_Marino.json +151 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Saudi_Arabia.json +97 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Serbia.json +93 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Singapore.json +112 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Slovakia.json +130 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Slovenia.json +116 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_South_Africa.json +103 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Spain.json +130 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Sweden.json +249 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Switzerland.json +114 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Trinidad_and_Tobago.json +144 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Tunisia.json +135 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Turkey.json +167 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Ukraine.json +144 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_United_Arab_Emirates.json +130 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_United_Kingdom.json +75 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_United_States.json +107 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Uruguay.json +208 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Venezuela.json +181 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Vietnam.json +96 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Yemen.json +134 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/not_checked/README.md +16 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/not_checked/date_Syria.json +147 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/not_checked/date_Thailand.json +290 -0
- black_beard_calendarium-0.2.0/src/calendarium/data/countries/toc.txt +112 -0
- black_beard_calendarium-0.2.0/src/calendarium/easter.py +49 -0
- black_beard_calendarium-0.2.0/src/calendarium/loader.py +98 -0
- black_beard_calendarium-0.2.0/src/calendarium/models.py +195 -0
- black_beard_calendarium-0.2.0/src/calendarium/rules.py +539 -0
- black_beard_calendarium-0.2.0/src/calendarium/snapshot.py +58 -0
- black_beard_calendarium-0.2.0/src/calendarium/toc.py +172 -0
- black_beard_calendarium-0.2.0/tests/test_calendars.py +80 -0
- black_beard_calendarium-0.2.0/tests/test_chinese.py +94 -0
- black_beard_calendarium-0.2.0/tests/test_cli.py +77 -0
- black_beard_calendarium-0.2.0/tests/test_easter.py +28 -0
- black_beard_calendarium-0.2.0/tests/test_engine.py +246 -0
- black_beard_calendarium-0.2.0/tests/test_golden.py +59 -0
- black_beard_calendarium-0.2.0/tests/test_loader.py +48 -0
- black_beard_calendarium-0.2.0/tests/test_referential.py +219 -0
- black_beard_calendarium-0.2.0/tests/test_rules.py +144 -0
- black_beard_calendarium-0.2.0/tests/test_toc.py +88 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 black beard
|
|
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,413 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: black-beard-calendarium
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Referential of computed dates (public holidays and observances) driven by per-country JSON rule files.
|
|
5
|
+
Author-email: Gael Beard <gaelgael5@gmail.com>
|
|
6
|
+
License: MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2026 black beard
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
27
|
+
|
|
28
|
+
Project-URL: Homepage, https://github.com/gaelgael5/calendarium
|
|
29
|
+
Keywords: holidays,calendar,dates,easter,hijri,observed
|
|
30
|
+
Classifier: Development Status :: 4 - Beta
|
|
31
|
+
Classifier: Intended Audience :: Developers
|
|
32
|
+
Classifier: Operating System :: OS Independent
|
|
33
|
+
Classifier: Programming Language :: Python :: 3
|
|
34
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
35
|
+
Requires-Python: >=3.9
|
|
36
|
+
Description-Content-Type: text/markdown
|
|
37
|
+
License-File: LICENSE
|
|
38
|
+
Provides-Extra: dev
|
|
39
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
40
|
+
Dynamic: license-file
|
|
41
|
+
|
|
42
|
+
# Calendarium
|
|
43
|
+
|
|
44
|
+
Referential of computed dates: public holidays and observances, driven by one
|
|
45
|
+
JSON configuration file per country whose date rules are written in a small
|
|
46
|
+
DSL.
|
|
47
|
+
|
|
48
|
+
Python port of [Black-Beard-Sdk/Calendarium](https://github.com/Black-Beard-Sdk/Calendarium)
|
|
49
|
+
(C#). The JSON configuration format is **unchanged**: the per-country files of
|
|
50
|
+
the original project are reused as-is and shipped with the package. The ANTLR
|
|
51
|
+
grammar of the original has been replaced by a small hand-written parser
|
|
52
|
+
(no code generation, no runtime dependency — the package only uses the
|
|
53
|
+
standard library).
|
|
54
|
+
|
|
55
|
+
## Installation
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pip install black-beard-calendarium
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
(The import name stays `calendarium`; the PyPI distribution is
|
|
62
|
+
`black-beard-calendarium` because the bare name was already taken.)
|
|
63
|
+
|
|
64
|
+
Development install with tests:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
pip install -e .[dev]
|
|
68
|
+
pytest
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Use by code
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
from datetime import date
|
|
75
|
+
from calendarium import Calendarium
|
|
76
|
+
|
|
77
|
+
# engine over the referential shipped with the package
|
|
78
|
+
cal = Calendarium.bundled()
|
|
79
|
+
|
|
80
|
+
# all dates of a year for a country
|
|
81
|
+
dates = cal.get_dates(2024, "France")
|
|
82
|
+
for d, identified in dates.items():
|
|
83
|
+
for event in identified.events:
|
|
84
|
+
print(d, event.name, event.observed, event.free)
|
|
85
|
+
|
|
86
|
+
# a specific region (region rules include the country-level ones)
|
|
87
|
+
cal.get_dates(2024, "France", region="67")
|
|
88
|
+
|
|
89
|
+
# every region of the country merged
|
|
90
|
+
cal.get_all_dates(2024, "France")
|
|
91
|
+
|
|
92
|
+
# one date
|
|
93
|
+
cal.get_date(date(2024, 7, 14), "France")
|
|
94
|
+
cal.is_free(date(2024, 7, 14), "France") # True
|
|
95
|
+
|
|
96
|
+
# a sliding window
|
|
97
|
+
cal.get_next_dates(date(2024, 12, 1), "France", count_days=60)
|
|
98
|
+
|
|
99
|
+
# index by observed date instead of actual date
|
|
100
|
+
cal.get_dates(2024, "France", key="observed")
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Custom configuration folders are supported:
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
cal = Calendarium.from_directory("path/to/countries")
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Loading countries from a TOC
|
|
110
|
+
|
|
111
|
+
Where the original .NET project shipped one NuGet package per country,
|
|
112
|
+
the Python version loads countries on demand from a **table of contents**:
|
|
113
|
+
a small text file listing `country;culture;uri`, one per line. Relative
|
|
114
|
+
URIs resolve against the TOC's own location, so the same file works over
|
|
115
|
+
HTTP, from a mirror, or from a local folder.
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
from calendarium import Calendarium, Toc, DEFAULT_TOC_URL
|
|
119
|
+
|
|
120
|
+
# the TOC published in this repository (raw GitHub)
|
|
121
|
+
cal = Calendarium.from_toc(DEFAULT_TOC_URL)
|
|
122
|
+
|
|
123
|
+
# pick countries by name or culture code
|
|
124
|
+
cal = Calendarium.from_toc(DEFAULT_TOC_URL, countries=["fr-FR", "Germany"])
|
|
125
|
+
|
|
126
|
+
# a TOC on disk or on any other site works the same way
|
|
127
|
+
cal = Calendarium.from_toc("/data/countries/toc.txt")
|
|
128
|
+
cal = Calendarium.from_toc("https://my-mirror.example.org/countries/toc.txt")
|
|
129
|
+
|
|
130
|
+
# inspect before loading, or add to a live engine
|
|
131
|
+
toc = Toc.load(DEFAULT_TOC_URL)
|
|
132
|
+
print(toc.countries())
|
|
133
|
+
cal.add_configuration(toc.load_country("fr-FR"))
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
From the command line: `calendarium countries --toc URI`,
|
|
137
|
+
`calendarium compute 2025 France --toc URI`.
|
|
138
|
+
|
|
139
|
+
The repository's TOC lives at `src/calendarium/data/countries/toc.txt`
|
|
140
|
+
and is regenerated with `python scripts/update_toc.py` whenever a country
|
|
141
|
+
is added. Note that the bundled referential ships inside the package
|
|
142
|
+
anyway — the TOC is for fetching configurations newer than your installed
|
|
143
|
+
package, or for serving your own curated set.
|
|
144
|
+
|
|
145
|
+
## Command line
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
# list the available country configurations
|
|
149
|
+
calendarium countries
|
|
150
|
+
|
|
151
|
+
# compute the dates of a year (table output)
|
|
152
|
+
calendarium compute 2024 France
|
|
153
|
+
|
|
154
|
+
# CSV output, same format as the original C# console
|
|
155
|
+
calendarium compute 2024 France --csv output.csv
|
|
156
|
+
|
|
157
|
+
# several years, one region only
|
|
158
|
+
calendarium compute 2024 France --years 2 --region 67
|
|
159
|
+
|
|
160
|
+
# festivities of one date
|
|
161
|
+
calendarium show 2024-07-14 France
|
|
162
|
+
|
|
163
|
+
# list the computed-date functions usable as [NAME] in rules
|
|
164
|
+
calendarium functions
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Add `--all` to also load the unverified configurations (see
|
|
168
|
+
[Data tiers](#data-tiers)), or `--data DIR` to load your own folder.
|
|
169
|
+
|
|
170
|
+
## Configuration format
|
|
171
|
+
|
|
172
|
+
One JSON file per country, named `date_<Country>.json` (`//` comments and
|
|
173
|
+
trailing commas are tolerated, as with the original Json.NET loader):
|
|
174
|
+
|
|
175
|
+
```json
|
|
176
|
+
{
|
|
177
|
+
"Country": "Poland",
|
|
178
|
+
"Culture": "pl",
|
|
179
|
+
"Calendar": "Gregorian",
|
|
180
|
+
"Regions": [ { "Key": "", "Periods": [], "From": null } ],
|
|
181
|
+
"Periods": [
|
|
182
|
+
{
|
|
183
|
+
"Name": "Fat Thursday",
|
|
184
|
+
"RuleDate": "([EASTER]) - 51",
|
|
185
|
+
"RuleObserved": null,
|
|
186
|
+
"RuleDuration": null,
|
|
187
|
+
"Free": false,
|
|
188
|
+
"Translations": [ { "Language": "French", "Name": "Mardi gras" } ],
|
|
189
|
+
"Tags": [],
|
|
190
|
+
"YearStart": 2014
|
|
191
|
+
}
|
|
192
|
+
]
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
* **Country** – key used to query the engine.
|
|
197
|
+
* **Calendar** – default calendar of the file; can be overridden per period.
|
|
198
|
+
* **Regions** – sub-country rule sets. A region inherits every country-level
|
|
199
|
+
period, plus its own; `From` additionally copies the periods of another
|
|
200
|
+
region of the same country (France: region `68` copies region `67`).
|
|
201
|
+
* **Periods** – the date rules:
|
|
202
|
+
* **Name** – English name (by convention);
|
|
203
|
+
* **RuleDate** – rule computing the date (see below);
|
|
204
|
+
* **RuleObserved** – rule computing the *observed* date when it differs
|
|
205
|
+
from the actual date (e.g. a holiday falling on a weekend);
|
|
206
|
+
* **RuleDuration** – rule computing the end date of a multi-day festivity;
|
|
207
|
+
* **Free** – whether the day is non-worked;
|
|
208
|
+
* **YearStart** / **YearEnd** – inclusive year bounds of the festivity
|
|
209
|
+
(`YearFrom` is accepted as an alias of `YearStart`);
|
|
210
|
+
* **Translations**, **Tags**, **Culture** – metadata carried to the events.
|
|
211
|
+
* **Defaults** – comma-separated names of shared `date_<Name>.Default.json`
|
|
212
|
+
configurations whose periods are imported (tagged with the default's name).
|
|
213
|
+
|
|
214
|
+
## Rules
|
|
215
|
+
|
|
216
|
+
A `RuleDate` is evaluated for a calendar year and produces one or more dates:
|
|
217
|
+
|
|
218
|
+
| Rule | Meaning |
|
|
219
|
+
|---|---|
|
|
220
|
+
| `"12-25"` | month 12, day 25, in the period's calendar |
|
|
221
|
+
| `"[EASTER]"` | a named computed date (see below) |
|
|
222
|
+
| `"([EASTER]) + 39"` | 39 days after Easter Sunday (Ascension) |
|
|
223
|
+
| `"([EASTER]) - 2"` | 2 days before Easter Sunday (Good Friday) |
|
|
224
|
+
| `"((11-23) - 1) << WEDNESDAY"` | first Wednesday on or before 22 November |
|
|
225
|
+
| `"(1-1) >> MONDAY"` | first Monday on or after 1 January |
|
|
226
|
+
| `"*MONDAY"` | every Monday of the year |
|
|
227
|
+
|
|
228
|
+
`>>` / `<<` move forward / backward to the given weekday and **stay in
|
|
229
|
+
place** when the date already falls on it.
|
|
230
|
+
|
|
231
|
+
A `RuleObserved` transforms a single date, usually behind a weekday
|
|
232
|
+
condition:
|
|
233
|
+
|
|
234
|
+
| Rule | Meaning |
|
|
235
|
+
|---|---|
|
|
236
|
+
| `"? (SATURDAY \| SUNDAY) : >> MONDAY"` | moved to next Monday when on a weekend |
|
|
237
|
+
| `"? SUNDAY : >> MONDAY"` | moved to next Monday when on a Sunday |
|
|
238
|
+
| `"? (FRIDAY \| SATURDAY) : >> SUNDAY"` | for Friday–Saturday weekends |
|
|
239
|
+
|
|
240
|
+
### Named computed dates
|
|
241
|
+
|
|
242
|
+
Available in any rule as `[NAME]`:
|
|
243
|
+
|
|
244
|
+
| Function | Computes |
|
|
245
|
+
|---|---|
|
|
246
|
+
| `[EASTER]` | Western Easter Sunday (Meeus/Jones/Butcher) |
|
|
247
|
+
| `[ORTHODOX_EASTER]` | Orthodox Easter Sunday (Julian computus, Gregorian date) |
|
|
248
|
+
| `[PASSOVER]` | Pesach I — 15 Nisan |
|
|
249
|
+
| `[ROSH_HASHANAH]` | 1 Tishri |
|
|
250
|
+
| `[YOM_KIPPUR]` | 10 Tishri |
|
|
251
|
+
| `[HANUKKAH]` | first day — 25 Kislev |
|
|
252
|
+
| `[VERNAL_EQUINOX_JAPAN]` | Shunbun no hi (official arithmetic formula, 1980–2099) |
|
|
253
|
+
| `[AUTUMNAL_EQUINOX_JAPAN]` | Shubun no hi (official arithmetic formula, 1980–2099) |
|
|
254
|
+
| `[MATARIKI]` | New Zealand gazetted Matariki dates (2022–2030) |
|
|
255
|
+
| `[JUNE_SOLSTICE_CHILE]` | Chilean Indigenous Peoples' Day (law 21.357 solstice dates) |
|
|
256
|
+
| `[QINGMING]` | Qingming festival — solar term at 15° (UTC+8) |
|
|
257
|
+
| `[DONGZHI]` | East Asian winter solstice festival (UTC+8) |
|
|
258
|
+
| `[DEEPAVALI]` | Gazetted Deepavali dates (2020–2026) |
|
|
259
|
+
|
|
260
|
+
The registry is extensible:
|
|
261
|
+
|
|
262
|
+
```python
|
|
263
|
+
from calendarium import register_function
|
|
264
|
+
register_function("MIDSUMMER", lambda year: [date(year, 6, 24)])
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
## Calendars
|
|
268
|
+
|
|
269
|
+
Rules can be expressed in a non-Gregorian calendar (`"Calendar"` at file or
|
|
270
|
+
period level); results are always returned as Gregorian dates. Supported:
|
|
271
|
+
|
|
272
|
+
* `Gregorian` (and `Default`), `Julian`;
|
|
273
|
+
* `Hebrew` — arithmetic Hebrew calendar (months numbered 1 = Nisan,
|
|
274
|
+
7 = Tishri, 13 = Adar II in leap years);
|
|
275
|
+
* `Hijri` and `UmAlQura` — tabular (civil) Islamic calendar, the same
|
|
276
|
+
arithmetic family as .NET's `HijriCalendar`. For `UmAlQura` this
|
|
277
|
+
approximates the Saudi lookup-table calendar: observed dates may differ by
|
|
278
|
+
one day;
|
|
279
|
+
* `Chinese`, `KoreanLunisolar`, `VietnameseLunisolar` — astronomical
|
|
280
|
+
Chinese lunisolar calendar (`calendarium.chinese`: Meeus new moons and
|
|
281
|
+
solar terms, winter-solstice anchored months, no-zhōngqì leap months),
|
|
282
|
+
computed at the national meridian (UTC+8 / UTC+9 / UTC+7) — which
|
|
283
|
+
reproduces, for instance, Tết 2007 falling one day before the Chinese
|
|
284
|
+
New Year;
|
|
285
|
+
* `Persian` — arithmetic Jalaali calendar;
|
|
286
|
+
* `ThaiBuddhist`, `Taiwan`, `Korean` — Gregorian with a year offset.
|
|
287
|
+
|
|
288
|
+
For a non-Gregorian period, the engine evaluates the rule for **every**
|
|
289
|
+
calendar year overlapping the requested Gregorian year and clips the results
|
|
290
|
+
to that year, so festivities near both ends of the Gregorian year are
|
|
291
|
+
produced exactly once.
|
|
292
|
+
|
|
293
|
+
## Observed day vs. public holiday
|
|
294
|
+
|
|
295
|
+
Each computed event carries both dates:
|
|
296
|
+
|
|
297
|
+
* `event.date` — the actual (legal) date of the festivity;
|
|
298
|
+
* `event.observed` — the date it is observed (`RuleObserved`), equal to
|
|
299
|
+
`event.date` when no rule applies;
|
|
300
|
+
* `event.free` — whether the festivity grants a non-working day;
|
|
301
|
+
* `event.is_shifted` — `True` when the two differ.
|
|
302
|
+
|
|
303
|
+
**Rule: the non-working day of a free festivity is its observed date.**
|
|
304
|
+
When nothing shifts the observance, observed and actual dates are the same
|
|
305
|
+
day and the distinction is invisible. When a `RuleObserved` shifts it (a
|
|
306
|
+
holiday falling on a weekend observed the following Monday), the actual date
|
|
307
|
+
keeps the identity of the festivity — name, translations, tags — but the day
|
|
308
|
+
off is the observed date. This matches the referential's documented intent
|
|
309
|
+
("the observed date is the free day") and the legal practice of the
|
|
310
|
+
countries using such rules.
|
|
311
|
+
|
|
312
|
+
Concretely:
|
|
313
|
+
|
|
314
|
+
* `event.is_free_on(d)` — `True` only when `d` is the event's observed date
|
|
315
|
+
and the festivity is free;
|
|
316
|
+
* `identified.free` and `Calendarium.is_free(d, country)` follow the same
|
|
317
|
+
rule (a festivity shifted away from `d` does not make `d` free);
|
|
318
|
+
* `get_dates(..., key="observed")` / `get_date(..., key="observed")` index
|
|
319
|
+
events by observed day, including observances shifted in from an adjacent
|
|
320
|
+
year (a 31 December holiday observed the following Monday appears in
|
|
321
|
+
January of the next year);
|
|
322
|
+
* weekends themselves are not modelled: `is_free` only reflects
|
|
323
|
+
festivity-driven days off.
|
|
324
|
+
|
|
325
|
+
## Data tiers
|
|
326
|
+
|
|
327
|
+
* `data/countries/` — verified configurations (109 countries). Each was
|
|
328
|
+
reviewed against its official holiday list, with substitute-day and
|
|
329
|
+
moving rules encoded (see the per-country git history), and is pinned by
|
|
330
|
+
a golden snapshot in `tests/golden/`.
|
|
331
|
+
* `data/countries/not_checked/` — the remaining unverified configurations
|
|
332
|
+
(Syria and Thailand), each blocked for a documented reason — see
|
|
333
|
+
[`not_checked/README.md`](src/calendarium/data/countries/not_checked/README.md).
|
|
334
|
+
Load them with `Calendarium.bundled(include_not_checked=True)` or the
|
|
335
|
+
CLI flag `--all`.
|
|
336
|
+
|
|
337
|
+
Dates on the tabular Islamic calendar are tagged in the files: countries
|
|
338
|
+
following actual moon sighting can differ by one day.
|
|
339
|
+
|
|
340
|
+
## Validating the referential
|
|
341
|
+
|
|
342
|
+
Every country file is validated by the test suite, in layers:
|
|
343
|
+
|
|
344
|
+
1. **Structure** (`tests/test_referential.py`) — each of the ~110 files is a
|
|
345
|
+
parametrized test case: metadata (strict for the verified tier), region
|
|
346
|
+
consistency, every rule parses, calendars resolve, and a `[FUNCTION]`
|
|
347
|
+
rule must run on a year-stable calendar.
|
|
348
|
+
2. **Evaluation invariants** — every file is evaluated over 2000–2030:
|
|
349
|
+
no error, dates clipped to the requested year, observed day within a
|
|
350
|
+
week of the actual day, and no dead rule (each period produces its dates
|
|
351
|
+
in every year it applies to; lunar-calendar periods may skip around the
|
|
352
|
+
Gregorian year boundary and are checked over two-year windows).
|
|
353
|
+
3. **Golden snapshots** (`tests/golden/<Country>.csv`, `tests/test_golden.py`)
|
|
354
|
+
— the business truth. A golden file is the human-reviewed output of a
|
|
355
|
+
country for pinned years; the suite recomputes and compares exactly.
|
|
356
|
+
Code cannot know that Bastille Day is correct: the review of the golden
|
|
357
|
+
diff against official sources is what certifies a country.
|
|
358
|
+
|
|
359
|
+
To (re)generate a golden file:
|
|
360
|
+
|
|
361
|
+
```bash
|
|
362
|
+
python scripts/update_golden.py France # one country
|
|
363
|
+
python scripts/update_golden.py --all-checked # the whole verified tier
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
**Promoting a country from `not_checked` to verified:**
|
|
367
|
+
|
|
368
|
+
1. review and fix its `date_<Country>.json` against official sources;
|
|
369
|
+
2. move the file from `data/countries/not_checked/` to `data/countries/`;
|
|
370
|
+
3. generate its golden file and review every line of it;
|
|
371
|
+
4. commit both — from then on, any change in its computed dates breaks CI.
|
|
372
|
+
|
|
373
|
+
## Differences from the C# version
|
|
374
|
+
|
|
375
|
+
* The ANTLR lexer/parser is replaced by a hand-written recursive-descent
|
|
376
|
+
parser (`calendarium.rules`); the accepted language is unchanged.
|
|
377
|
+
* `YearStart` / `YearEnd` are inclusive, as documented in the original
|
|
378
|
+
README (the C# engine skipped the boundary years).
|
|
379
|
+
* Non-Gregorian rules are evaluated over every calendar year overlapping the
|
|
380
|
+
requested Gregorian year (the C# engine evaluated a single one, missing
|
|
381
|
+
end-of-year festivities).
|
|
382
|
+
* New named dates: `[PASSOVER]`, `[ROSH_HASHANAH]`, `[YOM_KIPPUR]`,
|
|
383
|
+
`[HANUKKAH]`; the registry is user-extensible.
|
|
384
|
+
* The NuGet distribution commands of the console are gone: the referential
|
|
385
|
+
ships with the package.
|
|
386
|
+
|
|
387
|
+
## Releasing to PyPI
|
|
388
|
+
|
|
389
|
+
Releases are built and published by `.github/workflows/release.yml` when a
|
|
390
|
+
`v*` tag is pushed:
|
|
391
|
+
|
|
392
|
+
```bash
|
|
393
|
+
git tag v0.2.0 && git push origin v0.2.0
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
or manually from the GitHub **Actions** tab: select the *Release*
|
|
397
|
+
workflow, *Run workflow* on `main` (publishing uses the version from
|
|
398
|
+
`pyproject.toml`; bump it first, as PyPI refuses an already-published
|
|
399
|
+
version).
|
|
400
|
+
|
|
401
|
+
The workflow uses PyPI **trusted publishing** (no stored token): register
|
|
402
|
+
the publisher once on <https://pypi.org/manage/account/publishing/> with
|
|
403
|
+
repository `gaelgael5/calendarium`, workflow `release.yml` and environment
|
|
404
|
+
`pypi`. A local build is just:
|
|
405
|
+
|
|
406
|
+
```bash
|
|
407
|
+
python -m pip install build twine
|
|
408
|
+
python -m build && python -m twine check dist/*
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
## License
|
|
412
|
+
|
|
413
|
+
MIT — see [LICENSE](LICENSE).
|