Added about() functionality for qutip_qip

[claretgrace0801]

Description
For solving issue qutip/qutip-qip#51, I have added an about functionality for qutip_qip. Will also make the necessary PR in the qutip-qip repository for completing this issue.

Related issues or PRs
fixes qutip/qutip-qip#51

Changelog
Added a parameter to qutip's about function which defaults to "qutip". qutip's about can be called from qutip_qip with the argument of "qutip_qip" which will display information about qutip_qip.
Displaying qutip_qip's version and installation path.

[BoxiLi]

Thanks @claretgrace0801 for the PR. This is nice indeed that qutip_qip only needs to call qutip.about() and add some additional information.

As it is now, however, every new qutip family package needs to modify this to add their own info. I'm wondering if we can modify the code so that this only needs to be done once in qutip.about and any new family package just needs to call qutip.about(package_name) without having to write into qutip's source code.

It could be implemented e.g.

import importlib
package = importlib.import_module(package_name)
print(f"package_name: {package.__version__}")

Also, it would be helpful to add a test in the qutip-qip repo to check if the printed information indeed includes "qutip_qip", e.g. see https://docs.pytest.org/en/6.2.x/capture.html.

[coveralls]

Coverage decreased (-0.02%) to 69.912% when pulling f8ee7b5 on claretgrace0801:master into 7425775 on qutip:master.

[claretgrace0801]

I've made the changes. Now other libraries won't have to change anything in qutip.about.
I'll add a test in qutip_qip too.

[BoxiLi]

I just realize that test in qutip-qip won't work because this has to be merged and released first. The code looks fine to me. Will test it locally later.

@hodgestar Just to get a second opinion, what do you think about this? As it could also be used by further family packages like control.

[hodgestar]

@BoxiLi I'm -1 on adding such complexity to qutip.about. It's often used for bug reporting, and complexity has cause use issue in such places in the past. Especially the importing by name and the calls to inspect look like trouble.

I would suggest a simpler solution, which is to have about_family_pkg(title, extra_lines). That way family packages can supply their own title and extras and about() in qutip and other packages can just call about_family_pkg with the correct arguments.

[BoxiLi]

I see your point that we should keep those debugging tools as simple as possible. Instead of reading the version in qutip.about, we do it using a hook function in the family package that returns the repo name and version etc.

Something like

def about(family_pkgs=[]):
    ...
    for family_pkg in family_pkgs:
        package_name, package_version = family_pkg._about_family_pkg()
        print(....)

In this way we don't need to pass the string name of the package but just pass the package itself. If anything went wrong, it is just in the implementation of _about_family_pkg in the family packages.

[hodgestar]

At the expense of some complication, we could add entry_points to the family packages and then qutip.about() could just run through those. The upside is that the entry_points are not that complicated and that only qutip.about() would ever have to be called by users.

[hodgestar]

Pseudocode for entrypoint suggestion:

    entrypoints = importlib.metadata.entrypoints(group="qutip.about")
    for ep in entrypoints:
        about_func = ep.load()
        try:
            title, lines = about_func()
        except Exception as exc:
            title, lines = ep.name, [str(exc)]
        print(title)
        print("-" * title)
        print()
        for line in lines:
            print(line)
        print()

[BoxiLi]

Hi @claretgrace0801, could you have a look at this entrypoint approach and try to implement it? Something similar to the example that @hodgestar provided above.

The advantage of this entrypoints approach is that one only needs to call qutip.about() and all the family packages that correctly registered an entry point function will all be displayed. So there is no need to provide them as arguments.

There is also some discussion of entrypoint in #1500, but there we were talking about registering the whole qutip_qip package, here only the qutip_qip._about_family_pkg() function.

[claretgrace0801]

Sounds good. I'll try to implement the entrypoint approach, like what @hodgestar suggested.

[BoxiLi]

Hi @claretgrace0801, Any updates on this?

[claretgrace0801]

Sorry for the delay. I'll make a commit in a few days.

[claretgrace0801]

Hey @BoxiLi, please have a look at this. I've also committed to qutip/qutip-qip#138.

[BoxiLi]

@claretgrace0801 Thanks!

Looks good to me. A few minor suggestions.

Could you also add a test for this? You can follow the method used #1920 which mocks a family package.

[BoxiLi]

It is better to use importlib rather than pkg_resources as stated in their documentation. The latter might be deprecated in the future.

[BoxiLi]

Suggested change

	print(line)
	print(line)
	print()

Add an empty line incase there are other family packages