Determine and document policy on type hinting (and, relatedly, documentation of parameter and return types)

[beykyle]

This issue encapsulates a few related issues that need to be cleaned up in the code base. @jared321 please add a comment of I've missed anything. I think this issue can document the ongoing design discussion related to type hinting and documentation. Currently, I've chosen to use type hinting throughout, as I find it to be useful as a developer when looking at unfamiliar code. However, as pointed out by @jared321, the current type hinting is not always consistent with a) the documentation and b) the actual code. An example of this is in _run_frescox_simulation.py, where type hinting for the parameters filename and cwd suggest they must be pathlib.Path objects, the documentation suggests they can be Path or str objects, and the code is consistent with the documentation, ensuring they must be one of those two types.

This raises the question, should the code not accept any type that can be converted into a Path object (e.g. Path, str, some type fromos.path, etc)? Perhaps, rather than explicitly type checking, we should simply check that the conversion to Path works, and then go on to use the Path object in the code (as we do currently).

If this is what we decide upon, this complicates the type hinting. One solution would be something like this:

from typing import Union
from os import PathLike

PathLikeType = Union[str, bytes, PathLike[str], PathLike[bytes]]

But, IMO, this starts getting complicated. Additionally, there is the issue of _run_frescox_simulation being a low-level, internal function, with each package exposing it via a more limited interface bfrescox(pro).run_simulation, which should consistently hint and document shared arguments, but may provide, for example, defaults that don't exist in the lower level function.

This issue is for discussion on what the guidelines are for type hinting and type-related documentation in the code. The resolution of this issue will be

1. a clear policy on documentation and type hints included in the developer guide
2. a consistent implementation of those policies throughout the codebase

[beykyle]

Here is @jared321 's suggestion from slacl:

1. If a function provides type hints, it should provide all type hints (e.g., the return type as well)
2. If a function provides type hints, there should be no need to provide the argument and return types in the docstring since Sphinx should be able to identify types from the hints and insert this information in the rendered docs
3. I strongly suggest against manually documenting raised exceptions. Readers could reasonably assume that each function will provide in its docs all exceptions that could be raised. But this would include all exceptions raised by all functions called by that function. That would be very difficult to establish and maintain correct. Also, exceptions are self-documenting if they contain a clear, useful message.
4. Don't include in the docstring content linked to implementation details, especially details that users can access by inspecting the actual return object.

[beykyle]

A better type hinting solution might be

import os

def dosomething(fname_arg : str | bytes | os.PathLike):
    fname = os.fspath(fname_arg)   
    # fname = str(fname_arg) # would also work

From https://stackoverflow.com/a/78070015

[jared321]

I don't have much experience with type hints (yet). Could the package contain a file such as _common_types.py with contents such as

_PATH_LIKE_TYPES = [str, Path, bytes, ...]
PATH_LIKE_TYPE = Union[_PATH_LIKE_TYPES]

def _check_if_path_like(argument, name):
     if not isinstance(argument, _PATH_LIKE_TYPES):
          raise TypeError(f"{name} is not a known path-like type ({argument})")

Could code look like

from ._common_types import (
     PATH_LIKE_TYPE,
     _check_if_path_like
)

def my_function(filename: PATH_LIKE_TYPE) -> float
     """
     :param filename: Name including full path of file to load
     :return: The result of applying algorithm to file contents
     """
     _check_if_path_like(filename)

If so, we'd have to see if Sphinx can render type hints correctly.