Add type hinting

Signed-off-by: Thomas Lauf <thomas.lauf@tngtech.com>

Author: lauft

.github/workflows/pythonpackage.yml

@@ -15,6 +15,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install .
+        pip install types-python-dateutil
         pip install ruff mypy
     - name: Run ruff
       run: |

src/holidata/__init__.py

@@ -1,16 +1,18 @@
-from typing import Iterator
+from typing import Iterator, Union
 
 from holidata.emitters import Emitter
 from holidata.holiday import Country, Holiday
 from holidata.holidays import *
 
 
 class Holidata:
-    def __init__(self, holidays, emitter: Emitter = None):
+    def __init__(self, holidays: Iterator[Holiday], emitter: Union[Emitter, None] = None) -> None:
         self.holidays = holidays
         self.emitter = emitter
 
     def __str__(self) -> str:
+        if not self.emitter:
+            raise ValueError
         return self.emitter.output(self.holidays)
 
     def formatted_as(self, format_id: str) -> 'Holidata':
@@ -20,7 +22,7 @@ def formatted_as(self, format_id: str) -> 'Holidata':
 
 
 class Locale:
-    def __init__(self, country: Country, lang: str):
+    def __init__(self, country: Country, lang: str) -> None:
         self.country = country
         self.lang = lang
 
@@ -60,7 +62,7 @@ def get_emitter_for(identifier: str) -> Emitter:
     return emitter_class()
 
 
-def for_locale(country_id: str, lang_id: str = None) -> Locale:
+def for_locale(country_id: str, lang_id: Union[str, None] = None) -> Locale:
     country = get_country_for(country_id)
     lang_id = country.validate_language_or_get_default(lang_id)
 

src/holidata/emitters.py

@@ -1,31 +1,31 @@
 import csv
 import io
 import json
-from typing import Any, Callable, Dict, List
+from typing import Any, Callable, Dict, Iterator, List, Union
 
 from holidata.holiday import Holiday
 from holidata.plugin import PluginMount
 
 
 class Emitter(metaclass=PluginMount):
-    type: str = None
+    type: Union[str, None] = None
 
-    def __init__(self):
+    def __init__(self) -> None:
         if self.type is None:
             raise ValueError(f"Emitter {self.__class__.__name__} does not provide its type!")
 
     @staticmethod
-    def get(identifier: str) -> Callable[[], 'Emitter']:
+    def get(identifier: str) -> Union[Callable[[], 'Emitter'], None]:
         return Emitter.get_plugin(identifier, "type")
 
-    def output(self, holidays: List[Holiday]) -> str:
+    def output(self, holidays: Iterator[Holiday]) -> str:
         raise NotImplementedError
 
 
 class JsonEmitter(Emitter):
     type: str = "json"
 
-    def output(self, holidays: List[Holiday]) -> str:
+    def output(self, holidays: Iterator[Holiday]) -> str:
         export_data: List[Dict[str, Any]] = [h.as_dict() for h in holidays]
         export_data.sort(key=lambda x: (x["date"], x["description"], x["region"]))
         return "\n".join([json.dumps(h, ensure_ascii=False, sort_keys=False, indent=None, separators=(",", ":")) for h in export_data]) + "\n"
@@ -34,12 +34,12 @@ def output(self, holidays: List[Holiday]) -> str:
 class CsvEmitter(Emitter):
     type: str = "csv"
 
-    def output(self, holidays: List[Holiday]) -> str:
+    def output(self, holidays: Iterator[Holiday]) -> str:
         export_data: List[Dict[str, Any]] = [h.as_dict() for h in holidays]
         export_data.sort(key=lambda x: (x["date"], x["description"], x["region"]))
         result: io.StringIO = io.StringIO()
 
-        writer: csv.DictWriter = csv.DictWriter(
+        writer: csv.DictWriter[str] = csv.DictWriter(
             result,
             ["locale", "region", "date", "description", "type", "notes"],
             quoting=csv.QUOTE_ALL,
@@ -66,7 +66,7 @@ def _format_yaml(holiday: Dict[str, Any]) -> str:
 
         return output
 
-    def output(self, holidays: List[Holiday]) -> str:
+    def output(self, holidays: Iterator[Holiday]) -> str:
         export_data: List[Dict[str, Any]] = [h.as_dict() for h in holidays]
         export_data.sort(key=lambda x: (x["date"], x["description"], x["region"]))
 
@@ -94,7 +94,7 @@ def _format_xml(holiday: Dict[str, Any]) -> str:
         output += "  </holiday>\n"
         return output
 
-    def output(self, holidays: List[Holiday]) -> str:
+    def output(self, holidays: Iterator[Holiday]) -> str:
         export_data: List[Dict[str, Any]] = [h.as_dict() for h in holidays]
         export_data.sort(key=lambda x: (x["date"], x["description"], x["region"]))
 

src/holidata/holiday.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass
-from typing import Callable, Dict, Iterator, List, Union
+from typing import Callable, Dict, Iterator, List, Literal, Union
 
 import dateutil
 from arrow import Arrow
@@ -19,7 +19,7 @@ class Holiday:
     flags: str = ""
     notes: str = ""
 
-    def as_dict(self) -> dict:
+    def as_dict(self) -> Dict[str, str]:
         return {
             "locale": self.locale,
             "region": self.region,
@@ -31,26 +31,30 @@ def as_dict(self) -> dict:
 
 
 class HolidayGenerator:
-    def __init__(self, country_id: str, default_lang: str):
+    def __init__(self, country_id: str, default_lang: Union[str, None]) -> None:
         self.name_dict: Dict[str, str] = {}
         self.notes: str = ""
         self.regions: List[str] = [""]
         self.flags: str = ""
         self.date: Callable[[int], Union[Arrow, None]] = lambda year: None
         self.country_id: str = country_id
-        self.default_lang: str = default_lang
+        self.default_lang: Union[str, None] = default_lang
         self.filters: List[Callable[[int], bool]] = []
 
-    def with_name(self, name: str, lang: str = None) -> 'HolidayGenerator':
+    def with_name(self, name: str, lang: Union[str, None] = None) -> 'HolidayGenerator':
         lang = self.default_lang if lang is None else lang
+
+        if lang is None:
+            raise ValueError("No language specified and no default language was provided!")
+
         self.name_dict[lang] = name
         return self
 
     def with_names(self, name_dict: Dict[str, str]) -> 'HolidayGenerator':
         self.name_dict = name_dict
         return self
 
-    def on(self, date_func: Callable[[int], Arrow] = None) -> 'HolidayGenerator':
+    def on(self, date_func: Callable[[int], Union[Arrow, None]]) -> 'HolidayGenerator':
         self.date = date_func
         return self
 
@@ -128,27 +132,28 @@ class Country(metaclass=PluginMount):
     id: str
     languages: List[str]
     default_lang: Union[str, None] = None
-    easter_type: int
-    holiday_generators: list
-    regions: list
+    easter_type: Literal[1, 2, 3]
+    holiday_generators: List[HolidayGenerator]
+    regions: List['Region']
 
-    def __init__(self):
+    def __init__(self) -> None:
         if not self.id:
             raise ValueError(f"Country '{self.__class__.__name__}' does not provide an id!")
         if not self.languages:
             raise ValueError(f"Country '{self.__class__.__name__}' does not list any languages!")
         if self.default_lang is not None and self.default_lang not in self.languages:
             raise ValueError(f"Country '{self.__class__.__name__}' does not list language '{self.default_lang}'!")
 
-        self.default_lang = self.languages[0] if self.default_lang is None and len(self.languages) == 1 else self.default_lang
+        self.default_lang = self.languages[0] if self.default_lang is None and len(
+            self.languages) == 1 else self.default_lang
         self.holiday_generators = []
         self.regions = []
 
     @staticmethod
-    def get(identifier):
+    def get(identifier: str) -> Union[Callable[[], 'Country'], None]:
         return Country.get_plugin(identifier, "id")
 
-    def validate_language_or_get_default(self, lang_id: str) -> str:
+    def validate_language_or_get_default(self, lang_id: Union[str, None]) -> str:
         if lang_id and lang_id.lower() not in self.languages:
             raise ValueError(
                 f"Language '{lang_id}' is not defined for country '{self.id}'! Choose one of [{', '.join(self.languages)}].")
@@ -182,7 +187,7 @@ def wrapper(year: int) -> Arrow:
 
 
 class Region:
-    def __init__(self, id: str, country: Country):
+    def __init__(self, id: str, country: Country) -> None:
         self.id: str = id
         self.country: Country = country
         self.holiday_generators: List[HolidayGenerator] = []

src/holidata/holidays/AT/__init__.py

@@ -13,7 +13,7 @@ class AT(Country):
     languages = ["de"]
     easter_type = EASTER_WESTERN
 
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__()
 
         self.define_holiday() \

src/holidata/holidays/BE/__init__.py

@@ -13,7 +13,7 @@ class BE(Country):
     languages = ["de", "fr", "nl"]
     easter_type = EASTER_WESTERN
 
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__()
 
         self.define_holiday() \

src/holidata/holidays/BR/__init__.py

@@ -49,7 +49,7 @@ class BR(Country):
     languages = ["pt"]
     easter_type = EASTER_WESTERN
 
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__()
 
         self.define_holiday() \

src/holidata/holidays/CA/__init__.py

@@ -37,7 +37,7 @@ class CA(Country):
     languages = ["en", "fr"]
     easter_type = EASTER_WESTERN
 
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__()
 
         self.define_holiday() \

src/holidata/holidays/CH/__init__.py

@@ -13,7 +13,7 @@ class CH(Country):
     languages = ["de"]
     easter_type = EASTER_WESTERN
 
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__()
 
         self.define_holiday() \

src/holidata/holidays/CO/__init__.py

@@ -13,7 +13,7 @@ class CO(Country):
     languages = ["es"]
     easter_type = EASTER_WESTERN
 
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__()
 
         self.define_holiday() \