pyhf.optimize not introspectable with inspect.getsource et al.

Description

Trying to use inspect (from the stdlib) to inspect the source of pyhf.optimize raises an AttributeError.

Expected Behavior

The inspect functions should work and return the source code.

Steps to Reproduce

With pyhf 0.6.1 and python 3.7.6:

import pyhf
import inspect
# this works when you replace pyhf.optimize with sys.modules[type(pyhf.optimize).__module__]
for l in inspect.getsourcelines(pyhf.optimize)[0]: print(l) 

Checklist

• Run git fetch to get the most up to date version of master
• Searched through existing Issues to confirm this is not a duplicate issue
• Filled out the Description, Expected Behavior, Actual Behavior, and Steps to Reproduce sections above or have edited/removed them in a way that fully describes the issue

NB: I am not sure how this relates to #735 and #1402 . Would using def __getattr__(): <...> fix this?

[matthewfeickert]

@lhenkelm My apologies for the overly curt replies on Friday — that wasn’t helpful and definitely not encouraging behavior for you to have further interactions with the project or Scikit-HEP.

I also failed to say thanks for using pyhf in the first place. 😃 We do appreciate people adopting it into their workflows and even more the people who care enough about it to open Issues and discuss with us.

From the above replies, I think it is safe to say that in addition to checking the docs website that is generated from the codebase docstrings, we could probably do a better job in the public API of distinguishing between what is actually meant for the user. PR #1403 will help with this to some extent (as you already noted — thanks for also actually reading through Issues before opening this one 👍) and revisions related to Issue #735 will allow us to further clean up the public API as well so that things like trying to understand the between optimize vs. optimizer hopefully won’t be something users have to think about at all.

I’ll leave this closed for now, as it will be linked in the Issues we just mentioned and this is more related to the _OptimizerRetriever class that users shouldn’t need to interact with, but if there are additional things worth discussing here please let us know and we’re more than happy to reopen.

[lhenkelm]

Hi @matthewfeickert, thanks for the heads up! This is a very nice improvement for interactive exploration of the API. In particular, I notice the REPL / notebook tab-completion will now suggest pyhf.optimizer when prompted with pyhf.opt<+tab> (or similar), which as you & @lukasheinrich noted above, has a much more helpful documentation than pyhf.optimize.

One thing I am now wondering about: would it make sense to foolproof the interactive help even more by putting in a reference to the useful names to interrogate using help(…)? I.e. a line in the _OptimizerRetriever docstring to the effect of “The currently used optimizer is documented at pyhf.optimizer. For optimization using the iminuit backend refer to pyhf.optimize.minuit_optimizer. (etc.)”.

The same references could go in the module docstring too, but then the _OptimizerRetriever would need to be replaced/extended to allow the module docstring to be found. That way I would get the same redirection when clicking through the online API docs (and the alternative optimizers would be listed by help automatically, so no need to keep track in a docstring). But I believe you had good reasons to use the retriever, so I don’t want to ignorantly suggest scrapping it without understanding its purpose.