holidays 0.77__py3-none-any.whl → 0.79__py3-none-any.whl

holidays/holiday_base.py

@@ -55,57 +55,32 @@ YearArg = Union[int, Iterable[int]]
 
 
 class HolidayBase(dict[date, str]):
-    """
-    A `dict`-like object containing the holidays for a specific country (and
-    province or state if so initiated); inherits the `dict` class (so behaves
-    similarly to a `dict`). Dates without a key in the Holiday object are not
-    holidays.
-
-    The key of the object is the date of the holiday and the value is the name
-    of the holiday itself. When passing the date as a key, the date can be
-    expressed as one of the following formats:
-
-    * `datetime.datetime` type;
-    * `datetime.date` types;
-    * a `float` representing a Unix timestamp;
-    * or a string of any format (recognized by `dateutil.parser.parse()`).
+    """Represent a dictionary-like collection of holidays for a specific country or region.
 
-    The key is always returned as a `datetime.date` object.
-
-    To maximize speed, the list of holidays is built as needed on the fly, one
-    calendar year at a time. When you instantiate the object, it is empty, but
-    the moment a key is accessed it will build that entire year's list of
-    holidays. To pre-populate holidays, instantiate the class with the years
-    argument:
-
-        us_holidays = holidays.US(years=2020)
+    This class inherits from `dict` and maps holiday dates to their names. It supports
+    customization by country and, optionally, by province or state (subdivision). A date
+    not present as a key is not considered a holiday (or, if `observed` is `False`, not
+    considered an observed holiday).
 
-    It is generally instantiated using the
-    [country_holidays()][holidays.utils.country_holidays] function.
+    Keys are holiday dates, and values are corresponding holiday names. When accessing or
+    assigning holidays by date, the following input formats are accepted:
 
-    The key of the `dict`-like `HolidayBase` object is the
-    `date` of the holiday, and the value is the name of the holiday itself.
-    Dates where a key is not present are not public holidays (or, if
-    **observed** is False, days when a public holiday is observed).
+    * `datetime.date`
+    * `datetime.datetime`
+    * `float` or `int` (Unix timestamp)
+    * `str` of any format recognized by `dateutil.parser.parse()`
 
-    When passing the `date` as a key, the `date` can be expressed in one of the
-    following types:
+    Keys are always returned as `datetime.date` objects.
 
-    * `datetime.date`,
-    * `datetime.datetime`,
-    * a `str` of any format recognized by `dateutil.parser.parse()`,
-    * or a `float` or `int` representing a POSIX timestamp.
+    To maximize performance, the holiday list is lazily populated one year at a time.
+    On instantiation, the object is empty. Once a date is accessed, the full calendar
+    year for that date is generated, unless `expand` is set to `False`. To pre-populate
+    holidays, instantiate the class with the `years` argument:
 
-    The key is always returned as a `datetime.date` object.
-
-    To maximize speed, the list of public holidays is built on the fly as
-    needed, one calendar year at a time. When the object is instantiated
-    without a **years** parameter, it is empty, but, unless **expand** is set
-    to False, as soon as a key is accessed the class will calculate that entire
-    year's list of holidays and set the keys with them.
+        us_holidays = holidays.US(years=2020)
 
-    If you need to list the holidays as opposed to querying individual dates,
-    instantiate the class with the **years** parameter.
+    It is recommended to use the
+    [country_holidays()][holidays.utils.country_holidays] function for instantiation.
 
     Example usage:
 
@@ -163,14 +138,13 @@ class HolidayBase(dict[date, str]):
         >>> assert '2018-01-06' not in us_holidays
         >>> assert '2018-01-06' in us_pr_holidays
 
-    Append custom holiday dates by passing one of:
+    Append custom holiday dates by passing one of the following:
 
-    * a `dict` with date/name key/value pairs (e.g.
-      `{'2010-07-10': 'My birthday!'}`),
-    * a list of dates (as a `datetime.date`, `datetime.datetime`,
-      `str`, `int`, or `float`); `'Holiday'` will be used as a description,
-    * or a single date item (of one of the types above); `'Holiday'` will be
-      used as a description:
+    * A dict mapping date values to holiday names (e.g. `{'2010-07-10': 'My birthday!'}`).
+    * A list of date values (`datetime.date`, `datetime.datetime`, `str`, `int`, or `float`);
+      each will be added with 'Holiday' as the default name.
+    * A single date value of any of the supported types above; 'Holiday' will be used as
+      the default name.
 
     ```python
     >>> custom_holidays = country_holidays('US', years=2015)
@@ -325,7 +299,7 @@ class HolidayBase(dict[date, str]):
                 Requested holiday categories.
 
         Returns:
-            A `HolidayBase` object matching the **country** or **market**.
+            A `HolidayBase` object matching the `country` or `market`.
         """
         super().__init__()
 
@@ -436,10 +410,10 @@ class HolidayBase(dict[date, str]):
 
         The method supports the following input types:
 
-        * `datetime.date`,
-        * `datetime.datetime`,
-        * a `str` of any format recognized by `dateutil.parser.parse()`,
-        * or a `float` or `int` representing a POSIX timestamp.
+        * `datetime.date`
+        * `datetime.datetime`
+        * `float` or `int` (Unix timestamp)
+        * `str` of any format recognized by `dateutil.parser.parse()`
 
         Args:
             key:
@@ -617,10 +591,11 @@ class HolidayBase(dict[date, str]):
         """Convert various date-like formats to `datetime.date`.
 
         The method supports the following input types:
-        * `datetime.date`,
-        * `datetime.datetime`,
-        * a `str` of any format recognized by `dateutil.parser.parse()`,
-        * or a `float` or `int` representing a POSIX timestamp
+
+        * `datetime.date`
+        * `datetime.datetime`
+        * `float` or `int` (Unix timestamp)
+        * `str` of any format recognized by `dateutil.parser.parse()`
 
         Args:
             key:
@@ -816,9 +791,7 @@ class HolidayBase(dict[date, str]):
             self.tr = gettext
 
     def _is_leap_year(self) -> bool:
-        """
-        Returns True if the year is leap. Returns False otherwise.
-        """
+        """Returns True if the year is leap. Returns False otherwise."""
         return isleap(self._year)
 
     def _add_holiday(self, name: str, *args) -> Optional[date]:
@@ -899,12 +872,13 @@ class HolidayBase(dict[date, str]):
         return dt.weekday() in self.weekend
 
     def _populate(self, year: int) -> None:
-        """This is a private class that populates (generates and adds) holidays
+        """This is a private method that populates (generates and adds) holidays
         for a given year. To keep things fast, it assumes that no holidays for
         the year have already been populated. It is required to be called
-        internally by any country populate() method, while should not be called
+        internally by any country `populate()` method, while should not be called
         directly from outside.
-        To add holidays to an object, use the update() method.
+        To add holidays to an object, use the [update()][holidays.holiday_base.HolidayBase.update]
+        method.
 
         Args:
             year: The year to populate with holidays.
@@ -980,10 +954,10 @@ class HolidayBase(dict[date, str]):
             key:
                 The date expressed in one of the following types:
 
-                * `datetime.date`,
-                * `datetime.datetime`,
-                * a `str` of any format recognized by `dateutil.parser.parse()`,
-                * or a `float` or `int` representing a POSIX timestamp.
+                * `datetime.date`
+                * `datetime.datetime`
+                * `float` or `int` (Unix timestamp)
+                * `str` of any format recognized by `dateutil.parser.parse()`
 
             default:
                 The default value to return if no value is found.
@@ -1001,10 +975,10 @@ class HolidayBase(dict[date, str]):
             key:
                 The date expressed in one of the following types:
 
-                * `datetime.date`,
-                * `datetime.datetime`,
-                * a `str` of any format recognized by `dateutil.parser.parse()`,
-                * or a `float` or `int` representing a POSIX timestamp.
+                * `datetime.date`
+                * `datetime.datetime`
+                * `float` or `int` (Unix timestamp)
+                * `str` of any format recognized by `dateutil.parser.parse()`
 
         Returns:
             A list of holiday names if the date is a holiday, otherwise an empty list.
@@ -1116,6 +1090,7 @@ class HolidayBase(dict[date, str]):
         """Find the n-th working day from a given date.
 
         Moves forward if n is positive, or backward if n is negative.
+        If n is 0, returns the given date if it is a working day; otherwise the next working day.
 
         Args:
             key:
@@ -1128,10 +1103,11 @@ class HolidayBase(dict[date, str]):
         Returns:
             The calculated working day after shifting by n working days.
         """
-        direction = +1 if n > 0 else -1
+        direction = +1 if n >= 0 else -1
         dt = self.__keytransform__(key)
-        for _ in range(abs(n)):
-            dt = _timedelta(dt, direction)
+        for _ in range(abs(n) or 1):
+            if n:
+                dt = _timedelta(dt, direction)
             while not self.is_working_day(dt):
                 dt = _timedelta(dt, direction)
         return dt
@@ -1159,6 +1135,20 @@ class HolidayBase(dict[date, str]):
         days = (dt2 - dt1).days + 1
         return sum(self.is_working_day(_timedelta(dt1, n)) for n in range(days))
 
+    def is_weekend(self, key: DateLike) -> bool:
+        """Check if the given date's week day is a weekend day.
+
+        Args:
+            key:
+                The date to check.
+
+        Returns:
+            True if the date's week day is a weekend day, False otherwise.
+        """
+        # To prioritize performance we avoid reusing the internal
+        # `HolidayBase._is_weekend` method and perform the check directly instead.
+        return self.__keytransform__(key).weekday() in self.weekend
+
     def is_working_day(self, key: DateLike) -> bool:
         """Check if the given date is considered a working day.
 
@@ -1183,10 +1173,10 @@ class HolidayBase(dict[date, str]):
             key:
                 The date expressed in one of the following types:
 
-                * `datetime.date`,
-                * `datetime.datetime`,
-                * a `str` of any format recognized by `dateutil.parser.parse()`,
-                * or a `float` or `int` representing a POSIX timestamp.
+                * `datetime.date`
+                * `datetime.datetime`
+                * `float` or `int` (Unix timestamp)
+                * `str` of any format recognized by `dateutil.parser.parse()`
 
             default:
                 The default value to return if no match is found.
@@ -1290,10 +1280,10 @@ class HolidayBase(dict[date, str]):
 
                 Dates can be expressed in one or more of the following types:
 
-                * `datetime.date`,
-                * `datetime.datetime`,
-                * a `str` of any format recognized by `dateutil.parser.parse()`,
-                * or a `float` or `int` representing a POSIX timestamp.
+                * `datetime.date`
+                * `datetime.datetime`
+                * `float` or `int` (Unix timestamp)
+                * `str` of any format recognized by `dateutil.parser.parse()`
         """
         for arg in args:
             if isinstance(arg, dict):
@@ -1308,12 +1298,17 @@ class HolidayBase(dict[date, str]):
 
 class HolidaySum(HolidayBase):
     """
-    Returns a `dict`-like object resulting from the addition of two or
-    more individual dictionaries of public holidays. The original dictionaries
-    are available as a `list` in the attribute `holidays,` and
-    `country` and `subdiv` attributes are added
-    together and could become `list` s. Holiday names, when different,
-    are merged. All years are calculated (expanded) for all operands.
+    Combine multiple holiday collections into a single dictionary-like object.
+
+    This class represents the sum of two or more `HolidayBase` instances.
+    The resulting object behaves like a dictionary mapping dates to holiday
+    names, with the following behaviors:
+
+    * The `holidays` attribute stores the original holiday collections as a list.
+    * The `country` and `subdiv` attributes are combined from all operands and
+      may become lists.
+    * If multiple holidays fall on the same date, their names are merged.
+    * Holidays are generated (expanded) for all years included in the operands.
     """
 
     country: Union[str, list[str]]  # type: ignore[assignment]

holidays/registry.py

@@ -44,6 +44,7 @@ COUNTRIES: RegistryDict = {
     "belize": ("Belize", "BZ", "BLZ"),
     "benin": ("Benin", "BJ", "BEN"),
     "bermuda": ("Bermuda", "BM", "BMU"),
+    "bhutan": ("Bhutan", "BT", "BTN"),
     "bolivia": ("Bolivia", "BO", "BOL"),
     "bonaire_sint_eustatius_and_saba": ("BonaireSintEustatiusAndSaba", "BQ", "BES"),
     "bosnia_and_herzegovina": ("BosniaAndHerzegovina", "BA", "BIH"),
@@ -96,6 +97,7 @@ COUNTRIES: RegistryDict = {
     "french_polynesia": ("FrenchPolynesia", "PF", "PYF", "HolidaysPF"),
     "french_southern_territories": ("FrenchSouthernTerritories", "TF", "ATF", "HolidaysTF"),
     "gabon": ("Gabon", "GA", "GAB"),
+    "gambia": ("Gambia", "GM", "GMB"),
     "georgia": ("Georgia", "GE", "GEO"),
     "germany": ("Germany", "DE", "DEU"),
     "ghana": ("Ghana", "GH", "GHA"),
@@ -108,6 +110,7 @@ COUNTRIES: RegistryDict = {
     "guatemala": ("Guatemala", "GT", "GUA"),
     "guernsey": ("Guernsey", "GG", "GGY"),
     "guinea": ("Guinea", "GN", "GIN"),
+    "guinea_bissau": ("GuineaBissau", "GW", "GNB"),
     "guyana": ("Guyana", "GY", "GUY"),
     "haiti": ("Haiti", "HT", "HTI"),
     "honduras": ("Honduras", "HN", "HND"),
@@ -117,6 +120,7 @@ COUNTRIES: RegistryDict = {
     "india": ("India", "IN", "IND"),
     "indonesia": ("Indonesia", "ID", "IDN"),
     "iran": ("Iran", "IR", "IRN"),
+    "iraq": ("Iraq", "IQ", "IRQ"),
     "ireland": ("Ireland", "IE", "IRL"),
     "isle_of_man": ("IsleOfMan", "IM", "IMN"),
     "israel": ("Israel", "IL", "ISR"),
@@ -127,12 +131,14 @@ COUNTRIES: RegistryDict = {
     "jersey": ("Jersey", "JE", "JEY"),
     "kazakhstan": ("Kazakhstan", "KZ", "KAZ"),
     "kenya": ("Kenya", "KE", "KEN"),
+    "kiribati": ("Kiribati", "KI", "KIR"),
     "kuwait": ("Kuwait", "KW", "KWT"),
     "kyrgyzstan": ("Kyrgyzstan", "KG", "KGZ"),
     "laos": ("Laos", "LA", "LAO"),
     "latvia": ("Latvia", "LV", "LVA"),
     "lebanon": ("Lebanon", "LB", "LBN"),
     "lesotho": ("Lesotho", "LS", "LSO"),
+    "liberia": ("Liberia", "LR", "LBR"),
     "libya": ("Libya", "LY", "LBY"),
     "liechtenstein": ("Liechtenstein", "LI", "LIE"),
     "lithuania": ("Lithuania", "LT", "LTU"),
@@ -181,6 +187,7 @@ COUNTRIES: RegistryDict = {
     "paraguay": ("Paraguay", "PY", "PRY"),
     "peru": ("Peru", "PE", "PER"),
     "philippines": ("Philippines", "PH", "PHL"),
+    "pitcairn_islands": ("PitcairnIslands", "PN", "PCN"),
     "poland": ("Poland", "PL", "POL"),
     "portugal": ("Portugal", "PT", "PRT"),
     "puerto_rico": ("PuertoRico", "PR", "PRI", "HolidaysPR"),
@@ -208,6 +215,11 @@ COUNTRIES: RegistryDict = {
     "slovenia": ("Slovenia", "SI", "SVN"),
     "solomon_islands": ("SolomonIslands", "SB", "SLB"),
     "south_africa": ("SouthAfrica", "ZA", "ZAF"),
+    "south_georgia_and_the_south_sandwich_islands": (
+        "SouthGeorgiaAndTheSouthSandwichIslands",
+        "GS",
+        "SGS",
+    ),
     "south_korea": ("SouthKorea", "KR", "KOR", "Korea"),
     "spain": ("Spain", "ES", "ESP"),
     "sri_lanka": ("SriLanka", "LK", "LKA"),
@@ -215,6 +227,7 @@ COUNTRIES: RegistryDict = {
     "svalbard_and_jan_mayen": ("SvalbardAndJanMayen", "SJ", "SJM", "HolidaysSJ"),
     "sweden": ("Sweden", "SE", "SWE"),
     "switzerland": ("Switzerland", "CH", "CHE"),
+    "syrian_arab_republic": ("SyrianArabRepublic", "SY", "SYR"),
     "taiwan": ("Taiwan", "TW", "TWN"),
     "tanzania": ("Tanzania", "TZ", "TZA"),
     "thailand": ("Thailand", "TH", "THA"),
@@ -225,6 +238,7 @@ COUNTRIES: RegistryDict = {
     "trinidad_and_tobago": ("TrinidadAndTobago", "TT", "TTO"),
     "tunisia": ("Tunisia", "TN", "TUN"),
     "turkey": ("Turkey", "TR", "TUR"),
+    "turkmenistan": ("Turkmenistan", "TM", "TKM"),
     "turks_and_caicos_islands": ("TurksAndCaicosIslands", "TC", "TCA"),
     "tuvalu": ("Tuvalu", "TV", "TUV"),
     "ukraine": ("Ukraine", "UA", "UKR"),

holidays/utils.py

@@ -40,9 +40,9 @@ def country_holidays(
     language: Optional[str] = None,
     categories: Optional[CategoryArg] = None,
 ) -> HolidayBase:
-    """
-    Returns a new dictionary-like `HolidayBase` object for the public
-    holidays of the country matching **country** and other keyword arguments.
+    """Return a new dictionary-like [HolidayBase][holidays.holiday_base.HolidayBase] object.
+
+    Include public holidays for the country matching `country` and other keyword arguments.
 
     Args:
         country:
@@ -60,9 +60,9 @@ def country_holidays(
             is requested.
 
         observed:
-            Whether to include the dates of when public holiday are observed
+            Whether to include the dates of when public holidays are observed
             (e.g. a holiday falling on a Sunday being observed the following
-            Monday). False may not work for all countries.
+            Monday). `False` may not work for all countries.
 
         prov:
             *deprecated* use `subdiv` instead.
@@ -106,12 +106,12 @@ def country_holidays(
             Requested holiday categories.
 
     Returns:
-        A `HolidayBase` object matching the **country**.
+        A `HolidayBase` object matching the `country`.
 
     The key of the `dict`-like `HolidayBase` object is the
     `date` of the holiday, and the value is the name of the holiday itself.
     Dates where a key is not present are not public holidays (or, if
-    **observed** is False, days when a public holiday is observed).
+    `observed` is `False`, days when a public holiday is observed).
 
     When passing the `date` as a key, the `date` can be expressed in one of the
     following types:
@@ -125,12 +125,12 @@ def country_holidays(
 
     To maximize speed, the list of public holidays is built on the fly as
     needed, one calendar year at a time. When the object is instantiated
-    without a **years** parameter, it is empty, but, unless **expand** is set
-    to False, as soon as a key is accessed the class will calculate that entire
+    without a `years` parameter, it is empty, but, unless `expand` is set
+    to `False`, as soon as a key is accessed the class will calculate that entire
     year's list of holidays and set the keys with them.
 
     If you need to list the holidays as opposed to querying individual dates,
-    instantiate the class with the **years** parameter.
+    instantiate the class with the `years` parameter.
 
     Example usage:
 
@@ -236,14 +236,14 @@ def financial_holidays(
     observed: bool = True,
     language: Optional[str] = None,
 ) -> HolidayBase:
-    """
-    Returns a new dictionary-like :py:class:`HolidayBase` object for the public
-    holidays of the financial market matching **market** and other keyword
+    """Return a new dictionary-like [HolidayBase][holidays.holiday_base.HolidayBase] object.
+
+    Include public holidays for the financial market matching `market` and other keyword
     arguments.
 
     Args:
         market:
-            An ISO 3166-1 Alpha-2 market code.
+            An ISO 10383 MIC code.
 
         subdiv:
             Currently not implemented for markets (see documentation).
@@ -256,9 +256,9 @@ def financial_holidays(
             is requested.
 
         observed:
-            Whether to include the dates of when public holiday are observed
+            Whether to include the dates of when public holidays are observed
             (e.g. a holiday falling on a Sunday being observed the following
-            Monday). False may not work for all countries.
+            Monday). `False` may not work for all markets.
 
         language:
             Specifies the language in which holiday names are returned.
@@ -293,7 +293,7 @@ def financial_holidays(
             This behavior will be updated and formalized in v1.
 
     Returns:
-        A `HolidayBase` object matching the **market**.
+        A `HolidayBase` object matching the `market`.
 
     Example usage:
 
@@ -428,7 +428,7 @@ def list_supported_financial(include_aliases: bool = True) -> dict[str, list[str
 
     Args:
         include_aliases:
-            Whether to include entity aliases (e.g. TAR for ECB, XNYS for NYSE).
+            Whether to include entity aliases (e.g. NYSE for XNYS, TAR for XECB).
 
     Returns:
         A dictionary where key is a market code and value is a list of supported

holidays/version.py

@@ -10,4 +10,4 @@
 #  Website: https://github.com/vacanza/holidays
 #  License: MIT (see LICENSE file)
 
-__version__ = "0.77"
+__version__ = "0.79"