Added type-checking.

Author: john-hen

docs/conf.py

@@ -53,6 +53,7 @@
     'members':       True,             # Include module/class members.
     'member-order': 'bysource',        # Order members as in source file.
 }
+autodoc_typehints = 'none'             # Rendering type hints doesn't work.
 autosummary_generate = False           # Stub files are created by hand.
 add_module_names = False               # Drop module prefix from signatures.
 

mph/client.py

@@ -1,5 +1,7 @@
 """Provides the wrapper for a Comsol client instance."""
 
+from __future__ import annotations
+
 from .       import discovery
 from .model  import Model
 from .config import option
@@ -11,8 +13,9 @@
 from pathlib import Path
 from logging import getLogger
 
+from typing import overload, Iterator
+from jpype  import JClass
 
-log = getLogger(__package__)
 
 # The following look-up table is used by the `modules()` method. It is
 # based on the table on page 41 of Comsol 6.0's Programming Reference
@@ -72,6 +75,8 @@
     'WAVEOPTICS':               'Wave Optics',
 }
 
+log = getLogger(__package__)
+
 
 class Client:
     """
@@ -121,11 +126,31 @@ class Client:
 /com/comsol/model/util/ModelUtil.html
     """
 
+    version: str
+    """Comsol version (e.g., `'6.0'`) the client is running on."""
+
+    standalone: bool
+    """Whether this is a stand-alone client or connected to a server."""
+
+    port: int | None
+    """Port number on which the client has connected to the server."""
+
+    host: str | None
+    """Host name or IP address of the server the client is connected to."""
+
+    java: JClass
+    """Java model object that this class instance is wrapped around."""
+
     ############
     # Internal #
     ############
 
-    def __init__(self, cores=None, version=None, port=None, host='localhost'):
+    def __init__(self,
+        cores:   int = None,
+        version: str = None,
+        port:    int = None,
+        host:    str = 'localhost',
+    ):
 
         # Make sure this is the one and only client.
         if jpype.isJVMStarted():
@@ -206,27 +231,18 @@ def __init__(self, cores=None, version=None, port=None, host='localhost'):
             # Log that we're done so the start-up time may be inspected.
             log.info('Stand-alone client initialized.')
 
-        # Save and document instance attributes.
-        # It seems to be necessary to document the instance attributes here
-        # towards the end of the method. If done earlier, Sphinx would not
-        # render them in source-code order, even though that's what we
-        # request in the configuration. This might be a bug in Sphinx.
-        self.version = backend['name']
-        """Comsol version (e.g., `'6.0'`) the client is running on."""
+        # Save instance attributes.
+        self.version    = backend['name']
         self.standalone = standalone
-        """Whether this is a stand-alone client or connected to a server."""
-        self.port = None
-        """Port number on which the client has connected to the server."""
-        self.host = None
-        """Host name or IP address of the server the client is connected to."""
-        self.java = java
-        """Java model object that this class instance is wrapped around."""
+        self.port       = None
+        self.host       = None
+        self.java       = java
 
         # Try to connect to server if not a stand-alone client.
-        if not standalone and host:
+        if not standalone and host and port is not None:
             self.connect(port, host)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         if self.standalone:
             connection = 'stand-alone'
         elif self.port:
@@ -235,17 +251,17 @@ def __repr__(self):
             connection = 'disconnected'
         return f'{self.__class__.__name__}({connection})'
 
-    def __contains__(self, item):
+    def __contains__(self, item: str | Model) -> bool:
         if isinstance(item, str) and item in self.names():
             return True
         if isinstance(item, Model) and item in self.models():
             return True
         return False
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[Model]:
         yield from self.models()
 
-    def __truediv__(self, name):
+    def __truediv__(self, name: str) -> Model:
         if isinstance(name, str):
             for model in self:
                 if name == model.name():
@@ -262,25 +278,25 @@ def __truediv__(self, name):
     ##############
 
     @property
-    def cores(self):
+    def cores(self) -> int:
         """Number of processor cores (threads) the Comsol session is using."""
         cores = self.java.getPreference('cluster.processor.numberofprocessors')
         cores = int(str(cores))
         return cores
 
-    def models(self):
+    def models(self) -> list[Model]:
         """Returns all models currently held in memory."""
         return [Model(self.java.model(tag)) for tag in self.java.tags()]
 
-    def names(self):
+    def names(self) -> list[str]:
         """Returns the names of all loaded models."""
         return [model.name() for model in self.models()]
 
-    def files(self):
+    def files(self) -> list[Path]:
         """Returns the file-system paths of all loaded models."""
         return [model.file() for model in self.models()]
 
-    def modules(self):
+    def modules(self) -> list[str]:
         """Returns the names of available licensed modules/products."""
         names = []
         for (key, value) in modules.items():
@@ -295,7 +311,7 @@ def modules(self):
     # Interaction #
     ###############
 
-    def load(self, file):
+    def load(self, file: Path | str) -> Model:
         """Loads a model from the given `file` and returns it."""
         file = Path(file).resolve()
         if self.caching() and file in self.files():
@@ -307,6 +323,10 @@ def load(self, file):
         log.info('Finished loading model.')
         return model
 
+    @overload
+    def caching(self, state: None) -> bool: ...
+    @overload
+    def caching(self, state: bool): ...
     def caching(self, state=None):
         """
         Enables or disables caching of previously loaded models.
@@ -329,7 +349,7 @@ def caching(self, state=None):
             log.error(error)
             raise ValueError(error)
 
-    def create(self, name=None):
+    def create(self, name: str = None) -> Model:
         """
         Creates a new model and returns it as a [`Model`](#Model) instance.
 
@@ -345,7 +365,7 @@ def create(self, name=None):
         log.debug(f'Created model "{name}" with tag "{java.tag()}".')
         return model
 
-    def remove(self, model):
+    def remove(self, model: str | Model):
         """Removes the given [`model`](#Model) from memory."""
         if isinstance(model, str):
             if model not in self.names():
@@ -382,7 +402,7 @@ def clear(self):
     # Remote #
     ##########
 
-    def connect(self, port, host='localhost'):
+    def connect(self, port: int, host: str = 'localhost'):
         """
         Connects the client to a server.
 

mph/config.py

@@ -1,14 +1,21 @@
 """Manages configuration options."""
 
+from __future__ import annotations
+
 import configparser
 import os
 import platform
 from pathlib import Path
 from logging import getLogger
 
+from typing import overload, TypedDict
+
+
+class Options(TypedDict):
+    session:  str
+    caching:  bool
+    classkit: bool
 
-system = platform.system()
-log    = getLogger(__package__)
 
 options = {
     'session':  'platform-dependent',
@@ -17,11 +24,20 @@
 }
 """Default values for configuration options."""
 
+system = platform.system()
+log    = getLogger(__package__)
+
 
 ##########
 # Access #
 ##########
 
+@overload
+def option(name: None, value: None) ->  Options: ...
+@overload
+def option(name: str, value: None) -> str | bool | int | float: ...
+@overload
+def option(name: str, value: str | bool | int | float): ...
 def option(name=None, value=None):
     """
     Sets or returns the value of a configuration option.
@@ -46,7 +62,7 @@ def option(name=None, value=None):
 # Storage #
 ###########
 
-def location():
+def location() -> Path:
     """
     Returns the default location of the configuration file.
 
@@ -65,7 +81,7 @@ def location():
         return Path.home()/'MPh'
 
 
-def load(file=None):
+def load(file: Path | str = None):
     """
     Loads the configuration from the given `.ini` file.
 
@@ -104,7 +120,7 @@ def load(file=None):
                 options[key] = parser[section][key]
 
 
-def save(file=None):
+def save(file: Path | str = None):
     """
     Saves the configuration in the given `.ini` file.
 

mph/discovery.py

@@ -21,16 +21,32 @@
 found in an earlier step will be ignored, regardless of install location.
 """
 
+from __future__ import annotations
+
 import platform
 import subprocess
 import re
 from pathlib   import Path
 from functools import lru_cache
 from logging   import getLogger
 
+from typing import TypedDict
+
+
+class Backend(TypedDict):
+    name:   str
+    major:  int
+    minor:  int
+    patch:  int
+    build:  int
+    root:   Path
+    jvm:    Path
+    server: list[Path | str]
+
 
-log = getLogger(__package__)
 system = platform.system()
+log = getLogger(__package__)
+
 architectures = {
     'Windows': ['win64'],
     'Linux':   ['glnxa64'],
@@ -42,7 +58,7 @@
 # Version information #
 #######################
 
-def parse(version):
+def parse(version: str) -> tuple[str, int, int, int, int]:
     """
     Parses version information as returned by Comsol executable.
 
@@ -86,7 +102,7 @@ def parse(version):
 # Back-end discovery #
 ######################
 
-def search_registry():
+def search_registry() -> list[Path]:
     """Returns Comsol executables found in the Windows Registry."""
 
     log.debug('Searching Windows Registry for Comsol executables.')
@@ -153,7 +169,7 @@ def search_registry():
     return executables
 
 
-def search_disk():
+def search_disk() -> list[Path]:
     """Returns Comsol executables found on the file system."""
 
     log.debug('Searching file system for Comsol executables.')
@@ -201,7 +217,7 @@ def search_disk():
     return executables
 
 
-def lookup_comsol():
+def lookup_comsol() -> Path | None:
     """Returns Comsol executable if found on the system's search path."""
 
     log.debug('Looking for Comsol executable on system search path.')
@@ -238,7 +254,7 @@ def lookup_comsol():
 
 
 @lru_cache(maxsize=1)
-def find_backends():
+def find_backends() -> list[Backend]:
     """Returns the list of available Comsol back-ends."""
 
     log.debug('Searching system for available Comsol back-ends.')
@@ -296,12 +312,13 @@ def find_backends():
             continue
 
         # On Windows, check that server executable exists in same folder.
+        server: list[Path | str]
         if system == 'Windows':
-            server = ini.parent/'comsolmphserver.exe'
-            if not server.exists():
+            file = ini.parent/'comsolmphserver.exe'
+            if not file.exists():
                 log.debug(f'No server executable alongside "{ini.name}".')
                 continue
-            server = [server]
+            server = [file]
         else:
             server = [comsol, 'mphserver']
 
@@ -340,6 +357,7 @@ def find_backends():
             continue
 
         # Get version information from Comsol server.
+        command: list[Path | str]
         command = server + ['--version']
         command[0] = str(command[0])   # Needed to support Python 3.6 and 3.7.
         try:
@@ -351,7 +369,10 @@ def find_backends():
             # `universal_newlines` instead of `text` to support Python 3.6.
             if system == 'Windows':
                 arguments['creationflags'] = 0x08000000
-            process = subprocess.run(command, **arguments)
+            process = subprocess.run(
+                command,
+                **arguments,              # pyright: ignore[reportArgumentType]
+            )
         except subprocess.CalledProcessError:
             log.debug('Querying version information failed.')
             continue
@@ -395,7 +416,7 @@ def find_backends():
 # Back-end selection #
 ######################
 
-def backend(version=None):
+def backend(version: str = None) -> Backend:
     """
     Returns information about the Comsol back-end.