Merge pull request #2741 from vacanza/dev

v0.77

Author: arkid15r

.github/PULL_REQUEST_TEMPLATE.md

@@ -33,12 +33,9 @@ Your PR description goes here.
   Put an `x` in the boxes that apply. You can change them after PR is created.
 -->
 
-- [ ] I've followed the [contributing guidelines][contributing-guidelines]
-- [ ] I've successfully run `make check`, all checks and tests are green
+- [ ] I've read and followed the [contributing guidelines](https://github.com/vacanza/holidays/blob/dev/CONTRIBUTING.md).
+- [ ] I've run `make check` locally; all checks and tests passed.
 
 <!--
   Thanks again for your contribution!
 -->
-
-[contributing-guidelines]: https://github.com/vacanza/holidays/blob/dev/CONTRIBUTING.md
-[docs]: https://github.com/vacanza/holidays/tree/dev/docs/source

.gitignore

@@ -1,3 +1,4 @@
+__pycache__
 .coverage
 .github_token
 .gitpod.yml
@@ -16,8 +17,6 @@ coverage.lcov
 coverage.xml
 dist/
 docs/auto_gen_files/
-docs/build
-docs/source/_autosummary
 holidays/locale/pot/*.pot
 MANIFEST
 Pipfile

.pre-commit-config.yaml

@@ -25,7 +25,7 @@ repos:
           - --py39-plus
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.2
+    rev: v0.12.4
     hooks:
       - id: ruff-check
       - id: ruff-format
@@ -47,7 +47,7 @@ repos:
         exclude: ^(docs)
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.16.1
+    rev: v1.17.0
     hooks:
       - id: mypy
         additional_dependencies:

CHANGES.md

@@ -1,3 +1,30 @@
+# Version 0.77
+
+Released July 21, 2025
+
+- Refactor US holidays: consolidate duplicate `self._year` triggers (#2726 by @PPsyrius)
+- Add Cabo Verde holidays (#2654 by @Prateekshit73, @prateekshit-v, @sindhuraks)
+- Add Cayman Islands holidays (#2706 by @Abheelash-Mishra)
+- Add Central African Republic holidays (#2687 by @Prateekshit73, @arkid15r, @prateekshit-v)
+- Add Christmas Island holidays (#2623 by @anshonweb, @arkid15r)
+- Add Democratic Republic of the Congo holidays (#2702 by @Prateekshit73, @prateekshit-v)
+- Add Faroe Islands holidays (#2719 by @KJhellico, @arkid15r, @Shrot101)
+- Add Gibraltar holidays (#2720 by @Wasif-Shahzad, @arkid15r, @KJhellico)
+- Add Lebanon holidays (#2700 by @kritibirda26, @arkid15r)
+- Add Mali holidays (#2725 by @kritibirda26, @arkid15r)
+- Add Montserrat holidays (#2714 by @Wasif-Shahzad, @arkid15r, @KJhellico)
+- Add Niue holidays (#2737 by @Abheelash-Mishra, @arkid15r)
+- Add Norfolk Island holidays (#2716 by @anshonweb, @arkid15r)
+- Add Palestine holidays (#2701 by @Wasif-Shahzad)
+- Add Saint Vincent and the Grenadines holidays (#2608 by @waqar2403, @arkid15r, @PPsyrius)
+- Add Tokelau holidays (#2727 by @anshonweb, @arkid15r, @KJhellico)
+- Fix missing `StaticHolidays` in some countries (#2729 by @KJhellico)
+- Improve some variable naming (#2708 by @arkid15r)
+- Optimize dict in/get cases (#2707 by @arkid15r)
+- Update Georgia holidays (#2735 by @KJhellico)
+- Update Peru holidays: add 2023+ holidays (#2730 by @kplrm, @KJhellico)
+- Document `_add_holiday_*` pattern (#2721 by @williambdean, @arkid15r)
+
 # Version 0.76
 
 Released July 7, 2025

CONTRIBUTORS

@@ -35,6 +35,7 @@ Daniel Musketa
 Daniël Niemeijer
 David Hotham
 Devaraj K
+Diego Rosaperez
 Diogo Rosa
 Dorian Monnier
 Douglas Franklin
@@ -139,7 +140,9 @@ Shalom Donga
 Shaurya Uppal
 Sho Hirose
 Shreyansh Pande
+Shreyas Smarth
 Simon Gurcke
+Sindhura Kumbakonam Subramanian
 Sugato Ray
 Sylvain Pasche
 Sylvia van Os

README.md

@@ -105,7 +105,7 @@ and detailed information.
 
 ## Available Countries
 
-We currently support 208 country codes. The standard way to refer to a country is by using its [ISO
+We currently support 223 country codes. The standard way to refer to a country is by using its [ISO
 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes), the same used
 for domain names, and for a subdivision its [ISO 3166-2
 code](https://en.wikipedia.org/wiki/ISO_3166-2). Some countries have common or foreign names or
@@ -385,6 +385,13 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td></td>
 </tr>
 <tr>
+<td>Cabo Verde</td>
+<td>CV</td>
+<td>Municipalities: BR (Brava), BV (Boa Vista), CA (Santa Catarina), CF (Santa Catarina do Fogo), CR (Santa Cruz), MA (Maio), MO (Mosteiros), PA (Paul), PN (Porto Novo), PR (Praia), RB (Ribeira Brava), RG (Ribeira Grande), RS (Ribeira Grande de Santiago), SD (São Domingos), SF (São Filipe), SL (Sal), SM (São Miguel), SO (São Lourenço dos Órgãos), SS (São Salvador do Mundo), SV (São Vicente), TA (Tarrafal), TS (Tarrafal de São Nicolau)</td>
+<td>de, en_US, es, fr, <strong>pt_CV</strong></td>
+<td>OPTIONAL</td>
+</tr>
+<tr>
 <td>Cambodia</td>
 <td>KH</td>
 <td></td>
@@ -406,6 +413,20 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td>GOVERNMENT, OPTIONAL</td>
 </tr>
 <tr>
+<td>Cayman Islands</td>
+<td>KY</td>
+<td></td>
+<td><strong>en_GB</strong>, en_US</td>
+<td></td>
+</tr>
+<tr>
+<td>Central African Republic</td>
+<td>CF</td>
+<td></td>
+<td>en_US, <strong>fr</strong></td>
+<td></td>
+</tr>
+<tr>
 <td>Chad</td>
 <td>TD</td>
 <td></td>
@@ -427,6 +448,13 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td>HALF_DAY</td>
 </tr>
 <tr>
+<td>Christmas Island</td>
+<td>CX</td>
+<td></td>
+<td><strong>en_CX</strong>, en_US</td>
+<td></td>
+</tr>
+<tr>
 <td>Cocos Islands</td>
 <td>CC</td>
 <td></td>
@@ -525,6 +553,13 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td></td>
 </tr>
 <tr>
+<td>DR Congo</td>
+<td>CD</td>
+<td></td>
+<td>en_US, <strong>fr</strong></td>
+<td></td>
+</tr>
+<tr>
 <td>Ecuador</td>
 <td>EC</td>
 <td></td>
@@ -581,6 +616,13 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td>GOVERNMENT, WORKDAY</td>
 </tr>
 <tr>
+<td>Faroe Islands</td>
+<td>FO</td>
+<td></td>
+<td>da, en_US, <strong>fo</strong>, is, no, sv</td>
+<td>HALF_DAY</td>
+</tr>
+<tr>
 <td>Fiji</td>
 <td>FJ</td>
 <td></td>
@@ -651,6 +693,13 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td></td>
 </tr>
 <tr>
+<td>Gibraltar</td>
+<td>GI</td>
+<td></td>
+<td><strong>en_GB</strong>, en_US</td>
+<td></td>
+</tr>
+<tr>
 <td>Greece</td>
 <td>GR</td>
 <td></td>
@@ -875,6 +924,13 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td></td>
 </tr>
 <tr>
+<td>Lebanon</td>
+<td>LB</td>
+<td></td>
+<td><strong>ar</strong>, en_US</td>
+<td>BANK, GOVERNMENT</td>
+</tr>
+<tr>
 <td>Lesotho</td>
 <td>LS</td>
 <td></td>
@@ -945,6 +1001,13 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td></td>
 </tr>
 <tr>
+<td>Mali</td>
+<td>ML</td>
+<td></td>
+<td>en_US, <strong>fr</strong></td>
+<td></td>
+</tr>
+<tr>
 <td>Malta</td>
 <td>MT</td>
 <td></td>
@@ -1029,6 +1092,13 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td>CATHOLIC, HEBREW, ISLAMIC, ORTHODOX, WORKDAY</td>
 </tr>
 <tr>
+<td>Montserrat</td>
+<td>MS</td>
+<td></td>
+<td><strong>en_MS</strong>, en_US</td>
+<td></td>
+</tr>
+<tr>
 <td>Morocco</td>
 <td>MA</td>
 <td></td>
@@ -1106,6 +1176,20 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td></td>
 </tr>
 <tr>
+<td>Niue</td>
+<td>NU</td>
+<td></td>
+<td><strong>en_NU</strong>, en_US</td>
+<td></td>
+</tr>
+<tr>
+<td>Norfolk Island</td>
+<td>NF</td>
+<td></td>
+<td><strong>en_NF</strong>, en_US</td>
+<td></td>
+</tr>
+<tr>
 <td>Northern Mariana Islands (the)</td>
 <td>MP</td>
 <td>Can also be loaded as country US, subdivision MP</td>
@@ -1148,6 +1232,13 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td>ARMED_FORCES, HALF_DAY</td>
 </tr>
 <tr>
+<td>Palestine</td>
+<td>PS</td>
+<td></td>
+<td><strong>ar</strong>, en_US</td>
+<td>CATHOLIC, ORTHODOX</td>
+</tr>
+<tr>
 <td>Panama</td>
 <td>PA</td>
 <td></td>
@@ -1267,6 +1358,13 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td></td>
 </tr>
 <tr>
+<td>Saint Vincent and the Grenadines</td>
+<td>VC</td>
+<td></td>
+<td>en_US, <strong>en_VC</strong></td>
+<td></td>
+</tr>
+<tr>
 <td>Samoa</td>
 <td>WS</td>
 <td></td>
@@ -1449,6 +1547,13 @@ any) in brackets, available languages and additional holiday categories. All cou
 <td>WORKDAY</td>
 </tr>
 <tr>
+<td>Tokelau</td>
+<td>TK</td>
+<td></td>
+<td><strong>en_TK</strong>, en_US, tkl</td>
+<td></td>
+</tr>
+<tr>
 <td>Tonga</td>
 <td>TO</td>
 <td></td>

SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version | Supported          |
 |---------| ------------------ |
-| 0.76    | :white_check_mark: |
-| < 0.76  | :x:                |
+| 0.77    | :white_check_mark: |
+| < 0.77  | :x:                |
 
 ## Reporting a Vulnerability
 

docs/examples.md

@@ -338,6 +338,41 @@ for a country that is not supported yet:
 >>> hdays = NewCountryHolidays()
 ```
 
+We can use the `self._add_holiday_*` methods to specify holidays:
+
+``` python
+>>> class MovingHolidays(holidays.HolidayBase):
+>>>     def _populate(self, year):
+>>>         super()._populate(year)
+>>> 
+>>>         self._add_holiday_3rd_mon_of_jan("Martin Luther King Jr. Day")
+>>>         self._add_holiday_last_fri_of_feb("Last Friday of February")
+>>>         self._add_holiday_1st_mon_before_dec_25("Monday before Christmas")
+>>> moving = MovingHolidays(years=2025)
+```
+
+The supported `_add_holiday_*` patterns are:
+
+- `_add_holiday_<month>_<day>` for fixed-date holidays
+- `_add_holiday_<last/nth>_<weekday>_of_<month>` for holidays that occur on a specific weekday of a month
+- `_add_holiday_<n>_day(s)_<past/prior>_<last/nth>_<weekday>_of_<month>`
+- `_add_holiday_<nth>_<weekday>_<before/from>_<month>_<day>`
+- `_add_holiday_<n>_day(s)_<prior/past>_easter` (requires inheritance from `ChristianHolidays` holidays group)
+
+Some examples of these methods would be:
+
+- `_add_holiday_jan_1`
+- `_add_holiday_last_mon_of_feb`
+- `_add_holiday_1st_thu_of_nov`
+- `_add_holiday_2_days_prior_2nd_mon_of_jan`
+- `_add_holiday_1_day_past_last_fri_of_dec`
+- `_add_holiday_1st_tue_from_dec_25`
+- `_add_holiday_2nd_fri_before_jun_15`
+- `_add_holiday_2_days_prior_easter` (make sure to derive from `ChristianHolidays`)
+- `_add_holiday_1_day_past_easter` (make sure to derive from `ChristianHolidays`)
+
+You can find the implementation details at `HolidayBase.__getattr__` method.
+
 We can also include holidays for a subdivision (e.g. prov/state) in our new class:
 
 ``` python