Adding type hinting (#129)

Co-authored-by: Rachel Bittner <[email protected]>
Co-authored-by: Christopher Jacoby <[email protected]>

Author: 3 people

.github/workflows/run-tests.yml

@@ -26,6 +26,7 @@ jobs:
 
     - name: Install dependencies
       run: |
+        sudo apt-get update
         sudo apt-get install sox
         python -m pip install --upgrade pip
         python -m pip install flake8 pytest pytest-cov

setup.py

@@ -25,6 +25,7 @@
         license='BSD-3-Clause',
         install_requires=[
             'numpy >= 1.9.0',
+            'typing-extensions >=  3.7.4.2 '
         ],
         extras_require={
             'tests': [

sox/combine.py

@@ -7,24 +7,29 @@
 
 from __future__ import print_function
 
-from . import file_info
+from pathlib import Path
+from typing import Union, Optional, List
+
+from typing_extensions import Literal
+
 from . import core
-from .log import logger
-from .core import ENCODING_VALS
-from .core import is_number
-from .core import sox
-from .core import play
+from . import file_info
+from .core import ENCODING_VALS, EncodingValue
 from .core import SoxError
 from .core import SoxiError
 from .core import VALID_FORMATS
-
+from .core import is_number
+from .core import play
+from .core import sox
+from .log import logger
 from .transform import Transformer
 
-
 COMBINE_VALS = [
     'concatenate', 'merge', 'mix', 'mix-power', 'multiply'
 ]
 
+CombineType = Literal['concatenate', 'merge', 'mix', 'mix-power', 'multiply']
+
 
 class Combiner(Transformer):
     '''Audio file combiner.
@@ -38,8 +43,11 @@ class Combiner(Transformer):
     def __init__(self):
         super(Combiner, self).__init__()
 
-    def build(self, input_filepath_list, output_filepath, combine_type,
-              input_volumes=None):
+    def build(self,
+              input_filepath_list: Union[str, Path],
+              output_filepath: Union[str, Path],
+              combine_type: CombineType,
+              input_volumes: Optional[List[float]] = None):
         '''Builds the output_file by executing the current set of commands.
 
         Parameters
@@ -116,7 +124,10 @@ def build(self, input_filepath_list, output_filepath, combine_type,
                 logger.info("[SoX] {}".format(out))
             return True
 
-    def preview(self, input_filepath_list, combine_type, input_volumes=None):
+    def preview(self,
+                input_filepath_list: List[Union[str, Path]],
+                combine_type: CombineType,
+                input_volumes: Optional[List[float]] = None):
         '''Play a preview of the output with the current set of effects
 
         Parameters
@@ -155,8 +166,13 @@ def preview(self, input_filepath_list, combine_type, input_volumes=None):
 
         play(args)
 
-    def set_input_format(self, file_type=None, rate=None, bits=None,
-                         channels=None, encoding=None, ignore_length=None):
+    def set_input_format(self,
+                         file_type: Optional[List[str]] = None,
+                         rate: Optional[List[float]] = None,
+                         bits: Optional[List[int]] = None,
+                         channels: Optional[List[int]] = None,
+                         encoding: Optional[List[EncodingValue]] = None,
+                         ignore_length: Optional[List[bool]] = None):
         '''Sets input file format arguments. This is primarily useful when
         dealing with audio files without a file extension. Overwrites any
         previously set input file arguments.
@@ -312,7 +328,8 @@ def set_input_format(self, file_type=None, rate=None, bits=None,
         return self
 
 
-def _validate_file_formats(input_filepath_list, combine_type):
+def _validate_file_formats(input_filepath_list: List[Union[str, Path]],
+                           combine_type: CombineType):
     '''Validate that combine method can be performed with given files.
     Raises IOError if input file formats are incompatible.
     '''
@@ -322,7 +339,8 @@ def _validate_file_formats(input_filepath_list, combine_type):
         _validate_num_channels(input_filepath_list, combine_type)
 
 
-def _validate_sample_rates(input_filepath_list, combine_type):
+def _validate_sample_rates(input_filepath_list: List[Path],
+                           combine_type: CombineType):
     ''' Check if files in input file list have the same sample rate
     '''
     sample_rates = [
@@ -332,11 +350,12 @@ def _validate_sample_rates(input_filepath_list, combine_type):
         raise IOError(
             "Input files do not have the same sample rate. The {} combine "
             "type requires that all files have the same sample rate"
-            .format(combine_type)
+                .format(combine_type)
         )
 
 
-def _validate_num_channels(input_filepath_list, combine_type):
+def _validate_num_channels(input_filepath_list: List[Path],
+                           combine_type: CombineType):
     ''' Check if files in input file list have the same number of channels
     '''
     channels = [
@@ -347,12 +366,14 @@ def _validate_num_channels(input_filepath_list, combine_type):
             "Input files do not have the same number of channels. The "
             "{} combine type requires that all files have the same "
             "number of channels"
-            .format(combine_type)
+                .format(combine_type)
         )
 
 
-def _build_input_format_list(input_filepath_list, input_volumes=None,
-                             input_format=None):
+def _build_input_format_list(input_filepath_list: List[Path],
+                             input_volumes: Optional[List[float]] = None,
+                             input_format: Optional[List[List[str]]] = None) \
+        -> List[str]:
     '''Set input formats given input_volumes.
 
     Parameters
@@ -426,7 +447,8 @@ def _build_input_format_list(input_filepath_list, input_volumes=None,
     return input_format_list
 
 
-def _build_input_args(input_filepath_list, input_format_list):
+def _build_input_args(input_filepath_list: List[Path],
+                      input_format_list: List[str]) -> List[str]:
     ''' Builds input arguments by stitching input filepaths and input
     formats together.
     '''
@@ -446,7 +468,7 @@ def _build_input_args(input_filepath_list, input_format_list):
     return input_args
 
 
-def _validate_combine_type(combine_type):
+def _validate_combine_type(combine_type: List[CombineType]):
     '''Check that the combine_type is valid.
 
     Parameters
@@ -462,7 +484,7 @@ def _validate_combine_type(combine_type):
         )
 
 
-def _validate_volumes(input_volumes):
+def _validate_volumes(input_volumes: List[float]):
     '''Check input_volumes contains a valid list of volumes.
 
     Parameters
@@ -479,5 +501,5 @@ def _validate_volumes(input_volumes):
             if not core.is_number(vol):
                 raise ValueError(
                     "Elements of input_volumes must be numbers: found {}"
-                    .format(vol)
+                        .format(vol)
                 )

sox/core.py

@@ -1,24 +1,32 @@
 '''Base module for calling SoX '''
 
-from pathlib import Path
 import subprocess
+from pathlib import Path
 from subprocess import CalledProcessError
-from typing import Union
+from typing import Union, List, Optional, Tuple, Iterable, Any
 
 import numpy as np
+from typing_extensions import Literal
 
-from .log import logger
 from . import NO_SOX
+from .log import logger
 
 SOXI_ARGS = ['B', 'b', 'c', 'a', 'D', 'e', 't', 's', 'r']
 
 ENCODING_VALS = [
     'signed-integer', 'unsigned-integer', 'floating-point', 'a-law', 'u-law',
     'oki-adpcm', 'ima-adpcm', 'ms-adpcm', 'gsm-full-rate'
 ]
+EncodingValue = Literal[
+    'signed-integer', 'unsigned-integer', 'floating-point', 'a-law', 'u-law',
+    'oki-adpcm', 'ima-adpcm', 'ms-adpcm', 'gsm-full-rate'
+]
 
 
-def sox(args, src_array=None, decode_out_with_utf=True):
+def sox(args: Iterable[str],
+        src_array: Optional[np.ndarray] = None,
+        decode_out_with_utf: bool = True) -> \
+        Tuple[bool, Optional[Union[str, np.ndarray]], Optional[str]]:
     '''Pass an argument list to SoX.
 
     Parameters
@@ -95,11 +103,12 @@ def sox(args, src_array=None, decode_out_with_utf=True):
 class SoxError(Exception):
     '''Exception to be raised when SoX exits with non-zero status.
     '''
+
     def __init__(self, *args, **kwargs):
         Exception.__init__(self, *args, **kwargs)
 
 
-def _get_valid_formats():
+def _get_valid_formats() -> List[str]:
     ''' Calls SoX help for a lists of audio formats available with the current
     install of SoX.
 
@@ -164,7 +173,7 @@ def soxi(filepath: Union[str, Path], argument: str) -> str:
     return str(shell_output).strip('\n')
 
 
-def play(args):
+def play(args: Iterable[str]) -> bool:
     '''Pass an argument list to play.
 
     Parameters
@@ -212,11 +221,12 @@ def play(args):
 class SoxiError(Exception):
     '''Exception to be raised when SoXI exits with non-zero status.
     '''
+
     def __init__(self, *args, **kwargs):
         Exception.__init__(self, *args, **kwargs)
 
 
-def is_number(var):
+def is_number(var: Any) -> bool:
     '''Check if variable is a numeric value.
 
     Parameters
@@ -237,7 +247,7 @@ def is_number(var):
         return False
 
 
-def all_equal(list_of_things):
+def all_equal(list_of_things: List[Any]) -> bool:
     '''Check if a list contains identical elements.
 
     Parameters

sox/file_info.py

@@ -1,12 +1,14 @@
 ''' Audio file info computed by soxi.
 '''
 import os
+from numbers import Number
 from pathlib import Path
+from typing import List, Dict
 from typing import Optional, Union
 
 from .core import VALID_FORMATS
-from .core import soxi
 from .core import sox
+from .core import soxi
 from .log import logger
 
 
@@ -104,7 +106,7 @@ def comments(input_filepath: Union[str, Path]) -> str:
     return str(output)
 
 
-def duration(input_filepath: Union[str, Path]) -> float:
+def duration(input_filepath: Union[str, Path]) -> Optional[float]:
     '''
     Show duration in seconds, or None if not available.
 
@@ -259,7 +261,7 @@ def validate_input_file(input_filepath: Union[str, Path]) -> None:
         )
 
 
-def validate_input_file_list(input_filepath_list: Union[str, Path]) -> None:
+def validate_input_file_list(input_filepath_list: List[Union[str, Path]]) -> None:
     '''Input file list validation function. Checks that object is a list and
     contains valid filepaths that can be processed by SoX.
 
@@ -320,7 +322,7 @@ def validate_output_file(output_filepath: Union[str, Path]) -> None:
         )
 
 
-def file_extension(filepath: Union[str, Path]):
+def file_extension(filepath: Union[str, Path]) -> str:
     '''Get the extension of a filepath.
 
     Parameters
@@ -336,7 +338,7 @@ def file_extension(filepath: Union[str, Path]):
     return Path(filepath).suffix[1:].lower()
 
 
-def info(filepath: Union[str, Path]) -> dict:
+def info(filepath: Union[str, Path]) -> Dict[str, Union[str, Number]]:
     '''Get a dictionary of file information
 
     Parameters
@@ -370,7 +372,7 @@ def info(filepath: Union[str, Path]) -> dict:
     return info_dictionary
 
 
-def stat(filepath: Union[str, Path]) -> dict:
+def stat(filepath: Union[str, Path]) -> Dict[str, Optional[float]]:
     '''Returns a dictionary of audio statistics.
 
     Parameters
@@ -407,7 +409,7 @@ def _stat_call(filepath: Union[str, Path]) -> str:
     return stat_output
 
 
-def _parse_stat(stat_output: Union[str, Path]) -> dict:
+def _parse_stat(stat_output: str) -> Dict[str, Optional[float]]:
     '''Parse the string output from sox's stat function
 
     Parameters