Deprecate download/url args and add language arg in CommonVoice

Author: mthrok

torchaudio/datasets/commonvoice.py

@@ -1,6 +1,7 @@
 import os
+import warnings
 from pathlib import Path
-from typing import List, Dict, Tuple, Union
+from typing import List, Dict, Tuple, Union, Optional
 
 import torchaudio
 from torchaudio.datasets.utils import unicode_csv_reader
@@ -16,7 +17,6 @@
 # validated.tsv
 
 FOLDER_IN_ARCHIVE = "CommonVoice"
-URL = "english"
 VERSION = "cv-corpus-4-2019-12-10"
 TSV = "train.tsv"
 
@@ -90,8 +90,15 @@ class COMMONVOICE(Dataset):
         root (str or Path): Path to the directory where the dataset is found or downloaded.
         tsv (str, optional): The name of the tsv file used to construct the metadata.
             (default: ``"train.tsv"``)
-        url (str, optional): The URL to download the dataset from, or the language of
-            the dataset to download. (default: ``"english"``).
+        url (str, optional): Language of dataset. Deprecated. Please use ``language``.
+        folder_in_archive (str, optional): The top-level directory of the dataset.
+        version (str): Version string. (default: ``"cv-corpus-4-2019-12-10"``)
+            For the other allowed values, Please checkout https://commonvoice.mozilla.org/en/datasets.
+        download (bool, optional):
+            Deprecated. CommonVoice requires user agreement on the usage term and torchaudio no longer
+            provides download functionality. Providing ``True`` results in error.
+        language (str, optional):
+            the language of the dataset to download. (default: ``"english"``).
             Allowed language values are ``"tatar"``, ``"english"``, ``"german"``,
             ``"french"``, ``"welsh"``, ``"breton"``, ``"chuvash"``, ``"turkish"``, ``"kyrgyz"``,
             ``"irish"``, ``"kabyle"``, ``"catalan"``, ``"taiwanese"``, ``"slovenian"``,
@@ -101,11 +108,6 @@ class COMMONVOICE(Dataset):
             ``"russian"``, ``"indonesian"``, ``"arabic"``, ``"tamil"``, ``"interlingua"``,
             ``"latvian"``, ``"japanese"``, ``"votic"``, ``"abkhaz"``, ``"cantonese"`` and
             ``"romansh sursilvan"``.
-        folder_in_archive (str, optional): The top-level directory of the dataset.
-        version (str): Version string. (default: ``"cv-corpus-4-2019-12-10"``)
-            For the other allowed values, Please checkout https://commonvoice.mozilla.org/en/datasets.
-        download (bool, optional):
-            Whether to download the dataset if it is not found at root path. (default: ``False``).
     """
 
     _ext_txt = ".txt"
@@ -115,23 +117,43 @@ class COMMONVOICE(Dataset):
     def __init__(self,
                  root: Union[str, Path],
                  tsv: str = TSV,
-                 url: str = URL,
+                 url: Optional[str] = None,
                  folder_in_archive: str = FOLDER_IN_ARCHIVE,
                  version: str = VERSION,
-                 download: bool = False) -> None:
+                 download: Optional[bool] = None,
+                 language: Optional[str] = None) -> None:
         if download:
             raise RuntimeError(
                 "Common Voice dataset requires user agreement on the usage term, "
                 "and torchaudio no longer provides the download feature. "
                 "Please download the dataset manually and extract it in the root directory, "
                 "then provide the target language to `url` argument.")
-        if url not in _LANG_CODE:
-            raise ValueError(f"`url` must be one of available languages: {_LANG_CODE.keys()}")
+        if download is not None:  # download = False, which has no impact on funnctionality
+            warnings.warn(
+                "`download` argument is deprecated and will be removed in 0.9.0. "
+                "Please remove the argument.")
+        if url is not None and language is not None:
+            raise ValueError(
+                "`url` and `language` arguments can not be provided at the same time. "
+                "Please use `language`."
+            )
+        if url is not None:
+            warnings.warn(
+                "`url` argument is deprecated and will be removed in 0.9.0."
+                "Please use `language`.")
+            if url not in _LANG_CODE:
+                raise ValueError(f"`url` must be one of available languages: {_LANG_CODE.keys()}")
+            language = url
+        else:
+            language = language or 'english'
+            if language not in _LANG_CODE:
+                raise ValueError(
+                    f"`language` must be one of available languages: {_LANG_CODE.keys()}")
 
         # Get string representation of 'root' in case Path object is passed
         root = os.fspath(root)
 
-        lang_code = _LANG_CODE[url]
+        lang_code = _LANG_CODE[language]
         folder_in_archive = os.path.join(folder_in_archive, version, lang_code)
 
         self._path = os.path.join(root, folder_in_archive)