use type hints in APIs users will call: downloading, show type hint in documentation

covsirphy/downloading/downloader.py

@@ -1,3 +1,6 @@
+from __future__ import annotations
+from pathlib import Path
+import pandas as pd
 from covsirphy.util.error import NotRegisteredError, SubsetNotFoundError
 from covsirphy.util.validator import Validator
 from covsirphy.util.term import Term
@@ -12,74 +15,70 @@ class DataDownloader(Term):
     """Class to download datasets from the recommended data servers.
 
     Args:
-        directory (str or pathlib.Path): directory to save downloaded datasets
-        update_interval (int): update interval of downloading dataset
+        directory: directory to save downloaded datasets
+        update_interval: update interval of downloading dataset
 
     Note:
-        Location layers are fixed to ["ISO3", "Province", "City"]
+        Location layers are fixed to ['ISO3', 'Province', 'City'].
     """
     LAYERS = [Term.ISO3, Term.PROVINCE, Term.CITY]
 
-    def __init__(self, directory="input", update_interval=12, **kwargs):
+    def __init__(self, directory: str or Path = "input", update_interval: int = 12, **kwargs) -> None:
         self._directory = directory
         self._update_interval = Validator(update_interval, "update_interval").int(value_range=(0, None))
         self._gis = GIS(layers=self.LAYERS, country=self.ISO3, date=self.DATE)
 
-    def layer(self, country=None, province=None, databases=None):
+    def layer(self, country: str | None = None, province: str | None = None, databases: list[str] | None = None) -> pd.DataFrame:
         """Return the data at the selected layer.
 
         Args:
-            country (str or None): country name or None
-            province (str or None): province/state/prefecture name or None
-            databases (list[str] or None): databases to use or None (japan, covid19dh, google, owid).
-                "japan": COVID-19 Dataset in Japan,
-                "covid19dh": COVID-19 Data Hub,
-                "owid": Our World In Data,
-                "wpp": World Population Prospects by United nations.
+            country: country name or None
+            province: province/state/prefecture name or None
+            databases: databases to use or None (japan, covid19dh, owid).
+                Candidates are as follows.
 
-        Returns:
-            pandas.DataFrame:
-                Index
-                    reset index
-                Columns
-                    Date (pandas.Timestamp): observation date
-                    ISO3 (str): country names
-                    Province (str): province/state/prefecture names
-                    City (str): city names
-                    Country (str): country names (top level administration)
-                    Province (str): province names (2nd level administration)
-                    ISO3 (str): ISO3 codes
-                    Confirmed (pandas.Int64): the number of confirmed cases
-                    Fatal (pandas.Int64): the number of fatal cases
-                    Recovered (pandas.Int64): the number of recovered cases
-                    Population (pandas.Int64): population values
-                    Tests (pandas.Int64): the number of tests
-                    Product (pandas.Int64): vaccine product names
-                    Vaccinations (pandas.Int64): cumulative number of vaccinations
-                    Vaccinations_boosters (pandas.Int64): cumulative number of booster vaccinations
-                    Vaccinated_once (pandas.Int64): cumulative number of people who received at least one vaccine dose
-                    Vaccinated_full (pandas.Int64): cumulative number of people who received all doses prescribed by the protocol
-                    School_closing
-                    Workplace_closing
-                    Cancel_events
-                    Gatherings_restrictions
-                    Transport_closing
-                    Stay_home_restrictions
-                    Internal_movement_restrictions
-                    International_movement_restrictions
-                    Information_campaigns
-                    Testing_policy
-                    Contact_tracing
-                    Stringency_index
+                - "japan": COVID-19 Dataset in Japan,
+                - "covid19dh": COVID-19 Data Hub,
+                - "owid": Our World In Data,
+                - "wpp": World Population Prospects by United nations.
 
-        Note:
-            When @country is None, country-level data will be returned.
+        Returns:
+            A dataframe with reset index and the following columns.
 
-        Note:
-            When @country is a string and @province is None, province-level data in the country will be returned.
+                - Date (pandas.Timestamp): observation date
+                - ISO3 (str): country names
+                - Province (str): province/state/prefecture names
+                - City (str): city names
+                - Country (str): country names (the top level administration)
+                - Province (str): province names (the 2nd level administration)
+                - ISO3 (str): ISO3 codes
+                - Confirmed (pandas.Int64): the number of confirmed cases
+                - Fatal (pandas.Int64): the number of fatal cases
+                - Recovered (pandas.Int64): the number of recovered cases
+                - Population (pandas.Int64): population values
+                - Tests (pandas.Int64): the number of tests
+                - Product (pandas.Int64): vaccine product names
+                - Vaccinations (pandas.Int64): cumulative number of vaccinations
+                - Vaccinations_boosters (pandas.Int64): cumulative number of booster vaccinations
+                - Vaccinated_once (pandas.Int64): cumulative number of people who received at least one vaccine dose
+                - Vaccinated_full (pandas.Int64): cumulative number of people who received all doses prescribed by the protocol
+                - School_closing
+                - Workplace_closing
+                - Cancel_events
+                - Gatherings_restrictions
+                - Transport_closing
+                - Stay_home_restrictions
+                - Internal_movement_restrictions
+                - International_movement_restrictions
+                - Information_campaigns
+                - Testing_policy
+                - Contact_tracing
+                - Stringency_index
 
         Note:
-            When @country and @province are strings, city-level data in the province will be returned.
+            - When @country is None, country-level data will be returned.
+            - When @country is a string and @province is None, province-level data in the country will be returned.
+            - When @country and @province are strings, city-level data in the province will be returned.
         """
         db_dict = {
             "japan": _CSJapan,
@@ -103,14 +102,14 @@ def layer(self, country=None, province=None, databases=None):
         except NotRegisteredError:
             raise SubsetNotFoundError(geo=(country, province)) from None
 
-    def citations(self, variables=None):
+    def citations(self, variables: list[str] | None = None) -> list[str]:
         """
         Return citation list of the data sources.
 
         Args:
-            variables (list[str] or None): list of variables to collect or None (all available variables)
+            variables: list of variables to collect or None (all available variables)
 
         Returns:
-            list[str]: citation list
+            citations
         """
         return self._gis.citations(variables=variables)

docs/conf.py

@@ -9,7 +9,6 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
 import os
 import sys
 sys.path.insert(0, os.path.abspath('../'))
@@ -31,6 +30,8 @@
 extensions = [
     'sphinx.ext.napoleon',
     'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx_autodoc_typehints',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     'sphinx_rtd_theme',
@@ -86,6 +87,15 @@
 
 # -- Extension configuration -------------------------------------------------
 
+napoleon_use_param = True
+napoleon_use_rtype = False
+napoleon_use_ivar = True
+
+intersphinx_mapping = {
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+}
+
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.

pyproject.toml

@@ -59,14 +59,16 @@ jupyter = "^1.0.0"
 ipykernel = "^6.15.3"
 ipywidgets = "^8.0.2"
 docutils = "0.16"
-Sphinx = "5.1.1"
+Sphinx = "^5.2.3"
 sphinx-rtd-theme = "^1.0.0"
 sphinxcontrib-seqdiag = "^3.0.0"
 sphinx-copybutton = "^0.5.0"
 nbsphinx = "^0.8.9"
 Pillow = "^9.2.0"
 myst-parser = "^0.18.0"
 sympy = "^1.11.1"
+sphinx = "^5.2.3"
+sphinx-autodoc-typehints = "^1.19.4"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]
@@ -85,9 +87,5 @@ filterwarnings = ["error"]
 addopts = "--cov=covsirphy --cov-report=xml --cov-report=term-missing -vv --no-cov-on-fail -p no:cacheprovider --durations=1 --maxfail=1"
 
 [tool.deptry]
-ignore_obsolete = [
-    'pyarrow', 'tabulate', 'requests',
-]
-exclude = [
-    'tests', '.venv', 'example', 'docs',
-]
+ignore_obsolete = ['pyarrow', 'tabulate', 'requests']
+exclude = ['tests', '.venv', 'example', 'docs']