Add UNOFFICIAL category for the United States. (#1669)

README.rst

@@ -190,7 +190,7 @@ All other default values are highlighted with bold:
      - AS
      - Can also be loaded as country US, subdivision AS
      -
-     -
+     - UNOFFICIAL
    * - Andorra
      - AD
      - Parishes: 02, 03, 04, 05, 06, 07, 08
@@ -455,7 +455,7 @@ All other default values are highlighted with bold:
      - GU
      - Can also be loaded as country US, subdivision GU
      -
-     -
+     - UNOFFICIAL
    * - Guatemala
      - GT
      -
@@ -665,7 +665,7 @@ All other default values are highlighted with bold:
      - MP
      - Can also be loaded as country US, subdivision MP
      -
-     -
+     - UNOFFICIAL
    * - North Macedonia
      - MK
      -
@@ -720,7 +720,7 @@ All other default values are highlighted with bold:
      - PR
      - Can also be loaded as country US, subdivision PR
      -
-     -
+     - UNOFFICIAL
    * - Romania
      - RO
      -
@@ -840,17 +840,17 @@ All other default values are highlighted with bold:
      - UM
      - Can also be loaded as country US, subdivision UM
      -
-     -
+     - UNOFFICIAL
    * - United States of America (the)
      - US
      - States and territories: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY
      -
-     -
+     - UNOFFICIAL
    * - United States Virgin Islands (the)
      -
      - See Virgin Islands (U.S.)
      -
-     -
+     - UNOFFICIAL
    * - Uruguay
      - UY
      -
@@ -885,7 +885,7 @@ All other default values are highlighted with bold:
      - VI
      - Can also be loaded as country US, subdivision VI
      -
-     -
+     - UNOFFICIAL
    * - Zambia
      - ZM
      -

holidays/constants.py

@@ -44,6 +44,7 @@
 OPTIONAL = "optional"
 PUBLIC = "public"
 SCHOOL = "school"
+UNOFFICIAL = "unofficial"
 WORKDAY = "workday"
 
 CHINESE = "chinese"

holidays/countries/american_samoa.py

@@ -9,6 +9,7 @@
 #  Website: https://github.com/dr-prodigy/python-holidays
 #  License: MIT (see LICENSE file)
 
+from holidays.constants import PUBLIC, UNOFFICIAL
 from holidays.countries.united_states import US
 
 
@@ -18,12 +19,17 @@ class HolidaysAS(US):
     # https://en.wikipedia.org/wiki/ISO_3166-2:US#Subdivisions_included_in_ISO_3166-1
 
     country = "AS"
+    supported_categories = (PUBLIC, UNOFFICIAL)
     subdivisions = ()  # Override US subdivisions.
 
     def _populate_public_holidays(self) -> None:
         self.subdiv = "AS"
         super()._populate_public_holidays()
 
+    def _populate_unofficial_holidays(self) -> None:
+        self.subdiv = "AS"
+        super()._populate_unofficial_holidays()
+
 
 class AS(HolidaysAS):
     pass

holidays/countries/guam.py

@@ -9,6 +9,7 @@
 #  Website: https://github.com/dr-prodigy/python-holidays
 #  License: MIT (see LICENSE file)
 
+from holidays.constants import PUBLIC, UNOFFICIAL
 from holidays.countries.united_states import US
 
 
@@ -18,12 +19,17 @@ class HolidaysGU(US):
     # https://en.wikipedia.org/wiki/ISO_3166-2:US#Subdivisions_included_in_ISO_3166-1
 
     country = "GU"
+    supported_categories = (PUBLIC, UNOFFICIAL)
     subdivisions = ()  # Override US subdivisions.
 
     def _populate_public_holidays(self) -> None:
         self.subdiv = "GU"
         super()._populate_public_holidays()
 
+    def _populate_unofficial_holidays(self) -> None:
+        self.subdiv = "GU"
+        super()._populate_unofficial_holidays()
+
 
 class GU(HolidaysGU):
     pass

holidays/countries/northern_mariana_islands.py

@@ -9,6 +9,7 @@
 #  Website: https://github.com/dr-prodigy/python-holidays
 #  License: MIT (see LICENSE file)
 
+from holidays.constants import PUBLIC, UNOFFICIAL
 from holidays.countries.united_states import US
 
 
@@ -18,12 +19,17 @@ class HolidaysMP(US):
     # https://en.wikipedia.org/wiki/ISO_3166-2:US#Subdivisions_included_in_ISO_3166-1
 
     country = "MP"
+    supported_categories = (PUBLIC, UNOFFICIAL)
     subdivisions = ()  # Override US subdivisions.
 
     def _populate_public_holidays(self) -> None:
         self.subdiv = "MP"
         super()._populate_public_holidays()
 
+    def _populate_unofficial_holidays(self) -> None:
+        self.subdiv = "MP"
+        super()._populate_unofficial_holidays()
+
 
 class MP(HolidaysMP):
     pass

holidays/countries/puerto_rico.py

@@ -9,6 +9,7 @@
 #  Website: https://github.com/dr-prodigy/python-holidays
 #  License: MIT (see LICENSE file)
 
+from holidays.constants import PUBLIC, UNOFFICIAL
 from holidays.countries.united_states import US
 
 
@@ -18,12 +19,17 @@ class HolidaysPR(US):
     # https://en.wikipedia.org/wiki/ISO_3166-2:US#Subdivisions_included_in_ISO_3166-1
 
     country = "PR"
+    supported_categories = (PUBLIC, UNOFFICIAL)
     subdivisions = ()  # Override US subdivisions.
 
     def _populate_public_holidays(self) -> None:
         self.subdiv = "PR"
         super()._populate_public_holidays()
 
+    def _populate_unofficial_holidays(self) -> None:
+        self.subdiv = "PR"
+        super()._populate_unofficial_holidays()
+
 
 class PR(HolidaysPR):
     pass

holidays/countries/united_states.py

@@ -12,6 +12,7 @@
 from typing import Tuple, Union
 
 from holidays.calendars.gregorian import DEC
+from holidays.constants import PUBLIC, UNOFFICIAL
 from holidays.groups import ChristianHolidays, InternationalHolidays
 from holidays.observed_holiday_base import (
     ObservedHolidayBase,
@@ -42,6 +43,7 @@ class UnitedStates(ObservedHolidayBase, ChristianHolidays, InternationalHolidays
     """
 
     country = "US"
+    supported_categories = (PUBLIC, UNOFFICIAL)
     observed_label = "%s (observed)"
     subdivisions: Union[Tuple[()], Tuple[str, ...]] = (
         "AK",  # Alaska.
@@ -168,6 +170,9 @@ def _add_christmas_eve_holiday(self):
         )
 
     def _populate_subdiv_holidays(self):
+        if PUBLIC not in self.categories:
+            return None
+
         # Martin Luther King Jr. Day
         if self._year >= 1986 and self.subdiv not in {"AL", "AR", "AZ", "GA", "ID", "MS", "NH"}:
             self._add_holiday_3rd_mon_of_jan("Martin Luther King Jr. Day")
@@ -929,6 +934,43 @@ def _populate_subdiv_wv_public_holidays(self):
     def _populate_subdiv_wy_public_holidays(self):
         pass
 
+    def _populate_unofficial_holidays(self):
+        # Very common celebrated cultural days, but no official observance.
+        # Due to its nature, no in-lieus are observed.
+
+        # Valentine's Day
+        # While the modern iteration of Valentine's Day has started in the UK in 1797,
+        # it wasn't until 1847 in the US that this started to be observed here.
+
+        if self._year >= 1847:
+            self._add_holiday_feb_14("Valentine's Day")
+
+        # St. Patrick's Day
+        # Started in Boston in 1737 for the US.
+
+        self._add_holiday_mar_17("St. Patrick's Day")
+
+        # Halloween
+        # Halloween began in the US sometime around the 19th century.
+
+        self._add_holiday_oct_31("Halloween")
+
+        # Continental US non-Public dates
+
+        if self.subdiv not in {"AS", "GU", "MP", "PR", "UM", "VI"}:
+            # Groundhog Day
+            # First observed on Feb 2 in 1886 in Continental US + Hawaii.
+
+            if self._year >= 1886:
+                self._add_holiday_feb_2("Groundhog Day")
+
+            # Election Day
+            # May be duplicates for certain states which has this as their actual public holiday.
+            # The current US Presidential Election date pattern was codified in 1848 nationwide.
+
+            if self._year >= 1848 and self._year % 4 == 0:
+                self._add_holiday_1_day_past_1st_mon_of_nov("Election Day")
+
 
 class US(UnitedStates):
     pass

holidays/countries/united_states_minor_outlying_islands.py

@@ -9,6 +9,7 @@
 #  Website: https://github.com/dr-prodigy/python-holidays
 #  License: MIT (see LICENSE file)
 
+from holidays.constants import PUBLIC, UNOFFICIAL
 from holidays.countries.united_states import US
 
 
@@ -18,12 +19,17 @@ class HolidaysUM(US):
     # https://en.wikipedia.org/wiki/ISO_3166-2:US#Subdivisions_included_in_ISO_3166-1
 
     country = "UM"
+    supported_categories = (PUBLIC, UNOFFICIAL)
     subdivisions = ()  # Override US subdivisions.
 
     def _populate_public_holidays(self) -> None:
         self.subdiv = "UM"
         super()._populate_public_holidays()
 
+    def _populate_unofficial_holidays(self) -> None:
+        self.subdiv = "UM"
+        super()._populate_unofficial_holidays()
+
 
 class UM(HolidaysUM):
     pass

holidays/countries/united_states_virgin_islands.py

@@ -9,6 +9,7 @@
 #  Website: https://github.com/dr-prodigy/python-holidays
 #  License: MIT (see LICENSE file)
 
+from holidays.constants import PUBLIC, UNOFFICIAL
 from holidays.countries.united_states import US
 
 
@@ -18,12 +19,17 @@ class HolidaysVI(US):
     # https://en.wikipedia.org/wiki/ISO_3166-2:US#Subdivisions_included_in_ISO_3166-1
 
     country = "VI"
+    supported_categories = (PUBLIC, UNOFFICIAL)
     subdivisions = ()  # Override US subdivisions.
 
     def _populate_public_holidays(self) -> None:
         self.subdiv = "VI"
         super()._populate_public_holidays()
 
+    def _populate_unofficial_holidays(self) -> None:
+        self.subdiv = "VI"
+        super()._populate_unofficial_holidays()
+
 
 class VI(HolidaysVI):
     pass