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.
Files changed (145) hide show
  1. black_beard_calendarium-0.2.0/LICENSE +21 -0
  2. black_beard_calendarium-0.2.0/PKG-INFO +413 -0
  3. black_beard_calendarium-0.2.0/README.md +372 -0
  4. black_beard_calendarium-0.2.0/pyproject.toml +43 -0
  5. black_beard_calendarium-0.2.0/setup.cfg +4 -0
  6. black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/PKG-INFO +413 -0
  7. black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/SOURCES.txt +143 -0
  8. black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/dependency_links.txt +1 -0
  9. black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/entry_points.txt +2 -0
  10. black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/requires.txt +3 -0
  11. black_beard_calendarium-0.2.0/src/black_beard_calendarium.egg-info/top_level.txt +1 -0
  12. black_beard_calendarium-0.2.0/src/calendarium/__init__.py +83 -0
  13. black_beard_calendarium-0.2.0/src/calendarium/calendars.py +438 -0
  14. black_beard_calendarium-0.2.0/src/calendarium/chinese.py +269 -0
  15. black_beard_calendarium-0.2.0/src/calendarium/cli.py +193 -0
  16. black_beard_calendarium-0.2.0/src/calendarium/core.py +406 -0
  17. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Albania.json +127 -0
  18. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Algeria.json +107 -0
  19. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Andorra.json +172 -0
  20. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Angola.json +154 -0
  21. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Argentina.json +228 -0
  22. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Armenia.json +158 -0
  23. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Australia.json +82 -0
  24. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Austria.json +144 -0
  25. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Azerbaijan.json +172 -0
  26. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Bahrain.json +137 -0
  27. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Belarus.json +82 -0
  28. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Belgium.json +137 -0
  29. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Bolivia.json +150 -0
  30. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Bosnia_and_Herzegovina.json +143 -0
  31. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Brazil.json +175 -0
  32. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Brunei.json +157 -0
  33. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Bulgaria.json +119 -0
  34. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Canada.json +117 -0
  35. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Chile.json +213 -0
  36. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_China.json +113 -0
  37. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Colombia.json +252 -0
  38. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Congo_Democratic_Republic_of.json +117 -0
  39. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Costa_Rica.json +117 -0
  40. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Croatia.json +130 -0
  41. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Cyprus.json +134 -0
  42. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Czechia.json +116 -0
  43. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Denmark.json +187 -0
  44. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Dominican_Republic.json +168 -0
  45. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Ecuador.json +130 -0
  46. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Egypt.json +164 -0
  47. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_El_Salvador.json +109 -0
  48. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Equatorial_Guinea.json +129 -0
  49. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Estonia.json +102 -0
  50. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Finland.json +217 -0
  51. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_France.json +197 -0
  52. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Georgia.json +130 -0
  53. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Germany.json +162 -0
  54. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Greece.json +109 -0
  55. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Guatemala.json +171 -0
  56. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Holy_See_Vatican_City.json +117 -0
  57. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Honduras.json +147 -0
  58. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Hong_Kong_S_A_R.json +150 -0
  59. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Hungary.json +166 -0
  60. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Iceland.json +129 -0
  61. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_India.json +32 -0
  62. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Iran.json +252 -0
  63. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Iraq.json +181 -0
  64. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Ireland.json +95 -0
  65. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Israel.json +84 -0
  66. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Italy.json +109 -0
  67. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Jamaica.json +87 -0
  68. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Japan.json +151 -0
  69. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Jordan.json +137 -0
  70. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Kazakhstan.json +132 -0
  71. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Kenya.json +99 -0
  72. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Korea.json +140 -0
  73. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Kuwait.json +130 -0
  74. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Latvia.json +185 -0
  75. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Lebanon.json +170 -0
  76. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Liechtenstein.json +203 -0
  77. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Lithuania.json +208 -0
  78. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Luxembourg.json +123 -0
  79. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Macao_S_A_R.json +156 -0
  80. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Macedonia_FYRO.json +99 -0
  81. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Malaysia.json +153 -0
  82. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Malta.json +130 -0
  83. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Mexico.json +154 -0
  84. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Moldova.json +109 -0
  85. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Monaco.json +139 -0
  86. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Montenegro.json +92 -0
  87. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Morocco.json +152 -0
  88. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Netherlands.json +171 -0
  89. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_New_Zealand.json +104 -0
  90. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Nicaragua.json +116 -0
  91. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Nigeria.json +132 -0
  92. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Norway.json +182 -0
  93. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Oman.json +130 -0
  94. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Pakistan.json +144 -0
  95. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Panama.json +176 -0
  96. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Paraguay.json +159 -0
  97. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Peru.json +116 -0
  98. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Philippines.json +168 -0
  99. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Poland.json +192 -0
  100. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Portugal.json +130 -0
  101. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Puerto_Rico.json +146 -0
  102. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Qatar.json +85 -0
  103. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Romania.json +221 -0
  104. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Russia.json +130 -0
  105. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_San_Marino.json +151 -0
  106. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Saudi_Arabia.json +97 -0
  107. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Serbia.json +93 -0
  108. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Singapore.json +112 -0
  109. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Slovakia.json +130 -0
  110. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Slovenia.json +116 -0
  111. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_South_Africa.json +103 -0
  112. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Spain.json +130 -0
  113. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Sweden.json +249 -0
  114. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Switzerland.json +114 -0
  115. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Trinidad_and_Tobago.json +144 -0
  116. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Tunisia.json +135 -0
  117. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Turkey.json +167 -0
  118. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Ukraine.json +144 -0
  119. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_United_Arab_Emirates.json +130 -0
  120. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_United_Kingdom.json +75 -0
  121. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_United_States.json +107 -0
  122. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Uruguay.json +208 -0
  123. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Venezuela.json +181 -0
  124. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Vietnam.json +96 -0
  125. black_beard_calendarium-0.2.0/src/calendarium/data/countries/date_Yemen.json +134 -0
  126. black_beard_calendarium-0.2.0/src/calendarium/data/countries/not_checked/README.md +16 -0
  127. black_beard_calendarium-0.2.0/src/calendarium/data/countries/not_checked/date_Syria.json +147 -0
  128. black_beard_calendarium-0.2.0/src/calendarium/data/countries/not_checked/date_Thailand.json +290 -0
  129. black_beard_calendarium-0.2.0/src/calendarium/data/countries/toc.txt +112 -0
  130. black_beard_calendarium-0.2.0/src/calendarium/easter.py +49 -0
  131. black_beard_calendarium-0.2.0/src/calendarium/loader.py +98 -0
  132. black_beard_calendarium-0.2.0/src/calendarium/models.py +195 -0
  133. black_beard_calendarium-0.2.0/src/calendarium/rules.py +539 -0
  134. black_beard_calendarium-0.2.0/src/calendarium/snapshot.py +58 -0
  135. black_beard_calendarium-0.2.0/src/calendarium/toc.py +172 -0
  136. black_beard_calendarium-0.2.0/tests/test_calendars.py +80 -0
  137. black_beard_calendarium-0.2.0/tests/test_chinese.py +94 -0
  138. black_beard_calendarium-0.2.0/tests/test_cli.py +77 -0
  139. black_beard_calendarium-0.2.0/tests/test_easter.py +28 -0
  140. black_beard_calendarium-0.2.0/tests/test_engine.py +246 -0
  141. black_beard_calendarium-0.2.0/tests/test_golden.py +59 -0
  142. black_beard_calendarium-0.2.0/tests/test_loader.py +48 -0
  143. black_beard_calendarium-0.2.0/tests/test_referential.py +219 -0
  144. black_beard_calendarium-0.2.0/tests/test_rules.py +144 -0
  145. 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).