Add a few type hints and docstrings

Author: filmor

clr_loader/__init__.py

@@ -1,70 +1,81 @@
 from os.path import basename
+from typing import Optional, Any
 from .ffi import ffi
 
 
 __all__ = ["get_mono", "get_netfx", "get_coreclr"]
 
 
+RuntimeImpl = Any
+
+
 class ClrFunction:
-    def __init__(self, runtime, assembly, typename, func_name):
+    def __init__(
+        self, runtime: RuntimeImpl, assembly: str, typename: str, func_name: str
+    ):
         self._assembly = assembly
         self._class = typename
         self._name = func_name
 
         self._callable = runtime.get_callable(assembly, typename, func_name)
 
-    def __call__(self, buffer):
+    def __call__(self, buffer: bytes) -> int:
         buf_arr = ffi.from_buffer("char[]", buffer)
         return self._callable(ffi.cast("void*", buf_arr), len(buf_arr))
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<ClrFunction {self._class}.{self._name} in {basename(self._assembly)}>"
 
 
 class Assembly:
-    def __init__(self, runtime, path):
+    def __init__(self, runtime: RuntimeImpl, path: str):
         self._runtime = runtime
         self._path = path
 
-    def get_function(self, name, func=None):
+    def get_function(self, name: str, func: Optional[str] = None) -> ClrFunction:
         if func is None:
             name, func = name.rsplit(".", 1)
 
         return ClrFunction(self._runtime, self._path, name, func)
 
-    def __getitem__(self, name):
+    def __getitem__(self, name: str) -> ClrFunction:
         return self.get_function(name)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<Assembly {self._path} in {self._runtime}>"
 
 
 class Runtime:
-    def __init__(self, impl):
+    def __init__(self, impl: RuntimeImpl):
         self._impl = impl
 
-    def get_assembly(self, path):
+    def get_assembly(self, path: str) -> Assembly:
         return Assembly(self._impl, path)
 
-    def __getitem__(self, path):
+    def __getitem__(self, path: str) -> Assembly:
         return self.get_assembly(path)
 
 
-def get_mono(domain=None, config_file=None, path=None, gc=None):
+def get_mono(
+    domain: Optional[str] = None,
+    config_file: Optional[str] = None,
+    path: Optional[str] = None,
+    gc: Optional[str] = None,
+) -> Runtime:
     from .mono import Mono
 
     impl = Mono(domain=domain, config_file=config_file, path=path, gc=gc)
     return Runtime(impl)
 
 
-def get_coreclr(runtime_config, dotnet_root=None):
+def get_coreclr(runtime_config: str, dotnet_root: Optional[str] = None) -> Runtime:
     from .hostfxr import HostFxr
 
     impl = HostFxr(runtime_config=runtime_config, dotnet_root=dotnet_root)
     return Runtime(impl)
 
 
-def get_netfx(name=None, config_file=None):
+def get_netfx(name: Optional[str] = None, config_file: Optional[str] = None) -> Runtime:
     from .netfx import NetFx
 
     impl = NetFx(name=name, config_file=config_file)

clr_loader/ffi/__init__.py

@@ -1,9 +1,9 @@
 import glob
 import os
-import shutil
 import sys
+from typing import Optional
 
-import cffi
+import cffi  # type: ignore
 
 from . import hostfxr, mono, netfx
 
@@ -15,7 +15,7 @@
     ffi.cdef(cdef)
 
 
-def load_hostfxr(dotnet_root):
+def load_hostfxr(dotnet_root: str):
     hostfxr_name = _get_dll_name("hostfxr")
     hostfxr_path = os.path.join(dotnet_root, "host", "fxr", "?.*", hostfxr_name)
 
@@ -28,7 +28,7 @@ def load_hostfxr(dotnet_root):
     raise RuntimeError(f"Could not find a suitable hostfxr library in {dotnet_root}")
 
 
-def load_mono(path=None, gc=None):
+def load_mono(path: Optional[str] = None, gc: Optional[str] = None):
     # Preload C++ standard library, Mono needs that and doesn't properly link against it
     if sys.platform.startswith("linux"):
         ffi.dlopen("stdc++", ffi.RTLD_GLOBAL)
@@ -58,7 +58,7 @@ def load_netfx():
     return ffi.dlopen(path)
 
 
-def _get_dll_name(name):
+def _get_dll_name(name: str) -> str:
     if sys.platform == "win32":
         return f"{name}.dll"
     elif sys.platform == "darwin":

clr_loader/ffi/hostfxr.py

@@ -1,3 +1,5 @@
+# flake8: noqa
+
 import sys
 
 cdef = []

clr_loader/ffi/mono.py

@@ -1,3 +1,5 @@
+# flake8: noqa
+
 cdef = []
 
 cdef.append(

clr_loader/ffi/netfx.py

@@ -1,3 +1,5 @@
+# flake8: noqa
+
 cdef = [
     """
 typedef void* pyclr_domain;

clr_loader/util/__init__.py

@@ -3,9 +3,15 @@
 from .hostfxr_errors import get_hostfxr_error
 
 
-def check_result(err_code):
+def check_result(err_code: int) -> None:
+    """Check the error code of a .NET hosting API function and raise a
+    converted exception.
+
+    :raises ClrError: If the error code is `< 0`
+    """
+
     if err_code < 0:
-        hresult = err_code & 0xFFFFFFFF
+        hresult = err_code & 0xFFFF_FFFF
 
         error = get_coreclr_error(hresult)
         if not error:

clr_loader/util/clr_error.py

@@ -1,5 +1,14 @@
+from typing import Optional
+
+
 class ClrError(Exception):
-    def __init__(self, hresult, name=None, message=None, comment=None):
+    def __init__(
+        self,
+        hresult: int,
+        name: Optional[str] = None,
+        message: Optional[str] = None,
+        comment: Optional[str] = None,
+    ):
         self.hresult = hresult
         self.name = name
         self.message = message

clr_loader/util/coreclr_errors.py

@@ -1,7 +1,9 @@
+from typing import Dict, Optional
+
 from .clr_error import ClrError
 
 
-def get_coreclr_error(hresult):
+def get_coreclr_error(hresult: int) -> Optional[ClrError]:
     name = SymbolicName.get(hresult)
     if not name:
         return None
@@ -14,9 +16,9 @@ def get_coreclr_error(hresult):
     )
 
 
-Comment = {}
-SymbolicName = {}
-Message = {}
+Comment: Dict[int, str] = {}
+SymbolicName: Dict[int, str] = {}
+Message: Dict[int, str] = {}
 
 
 if __name__ == "__main__":
@@ -48,8 +50,7 @@ def get_coreclr_error(hresult):
 
     for row in tree.findall(".//HRESULT"):
         try:
-            numeric_value = row.attrib["NumericValue"]
-            numeric_value = int(numeric_value, base=16)
+            numeric_value = int(row.attrib["NumericValue"], base=16)
 
             for child in row:
                 if child.text:

clr_loader/util/hostfxr_errors.py

@@ -1,11 +1,15 @@
+from typing import Optional
+
 from .clr_error import ClrError
 
 __all__ = ["get_hostfxr_error"]
 
 
-def get_hostfxr_error(hresult):
+def get_hostfxr_error(hresult: int) -> Optional[ClrError]:
     if hresult in HOSTFXR_ERRORS:
         return ClrError(hresult, HOSTFXR_ERRORS[hresult])
+    else:
+        return None
 
 
 _ERRORS = dict(