Design considerations - 'deeplabcut' Python package and DeepLabCut Application #1895

Note that this is a meta-issue. I'm not discussing one-specific issue here. Rather, i'm trying to document big picture/design decisions in the current package/application, decisions which add friction when integrating deeplabcut into external applications. I'd like comments/feedback from the authors/maintainers regarding these points.

In this issue, I will be using "DeepLabCut" to refer to the end-user Application and deeplabcut to refer to Python package.

Based on my understanding, DeepLabCut was built as an end user application. There are a number of design considerations in the deeplabcut package that make sense from the point of view of DeepLabCut. But, when an external application tries to integrate deeplabcut, there are a number of awkward workarounds/misfits.

For example, DeepLabCut controls the configuration file, the directory containing the results and the filenames of the result files. The functions in deeplabcut used by DeepLabCut create pandas DataFrames, which are what get saved to disk, but they are not returned by the functions.

Another example is the type hints in the package. Widespread adoption of type hints in the package might not be necessary but adding type hints for all top-level functions should improve usability of deeplabcut in external applications (e.g. documented in https://deeplabcut.github.io/DeepLabCut/docs/standardDeepLabCut_UserGuide.html).

Another example is print calls to sys.stdout in deeplabcut. DeepLabCut needs to convey information to the user but the use of print calls in deeplabcut mean that applications that don't want to print these messages to stdout will have to resort to monkeypatching sys.stdout/sys.stderr to capture the print messages and redirect them as logging messages. This can be resolved by adding a logger to the DeepLabCut application and replacing the print calls with logger.* calls e.g. logger.info/logger.error/logger.warning.

Another example is uniform usage of str or pathlib.Path objects as filepaths to configuration file, video files, destination folders etc. At the moment, it's not clear from the docstrings in deeplabcut whether the functions accept pathlib.Path objects, resulting in trial-and-error to figure this out (or digging into the code) or resulting in the external application being conservative by only passing string paths.

Another example is the separation of library dependencies vs application dependencies, specifically matplotlib. Users of the deeplabcut package might not be interested in functionality deeplabcut provides using matplotlib so preventing matplotlib imports from modules that are "core" to deeplabcut would be useful.