Fixed issue 6612 by covering ibmq examples by lint check

[dhruvbhq]

Summary

Fixes #6612

Details and comments

The ibmq examples were not being covered by lint checks. This PR fixes lint errors in ibmq examples and covers them by the lint checks.

1. Added __init__.py files to convert qiskit examples to package to facilitate lint checking
2. Updated Makefile and tox.ini lint targets to cover ibmq examples as well
3. Updated Make.bat batch file to make it consistent with these and other recent changes
4. Fixed up lint errors found
5. The check C0114 (missing module docstring) is no longer disabled in examples, as it is good to have docstrings.

[dhruvbhq]

Hi, as some things are new to me, I'd like to discuss some points about this PR:

1. I got two lint errors while running pylint on ibmq examples: E0611: no name 'ibmq' in module 'qiskit.providers' and E0401: Unable to import 'qiskit.providers.ibmq'. These were appearing even after doing 'pip install qiskit-ibmq-provider'. When trying to run the ibmq examples locally, 'import qiskit.providers.ibmq' is able to locate it in 'virtualenvpath'/lib/site-packages/qiskit/providers/ibmq. However, I believe pylint is looking for it in qiskit-terra/qiskit/providers, where it is not present. Therefore, I think the pylint check is too strict in this case and I believe it is appropriate to disable these two checks in the lint targets. If there is a better solution to this, I'd love to hear. @levbishop

2. From what I could understand by reading the code, examples are not yet checked by pylint in the azure_pipelines.yml. Is there a reason for doing so? I think azure_pipelines.yml should be updated similarly too.

Thanks :)

[1ucian0]

Hi @dhruvbhq !

Sorry we missed this one. Is your first point ("Added __init__.py files to convert qiskit examples to package to facilitate lint checking") necessary? Im not sure if the examples are being packaged.

[dhruvbhq]

Hi @1ucian0!

I haven't looked at this in a while, but I think what I did/meant was this:

In the Makefile, the lint target runs pylint ... on examples/python/*.py . See here.

However, the IBMQ examples are present as examples/python/ibmq/*.py, so the above implementation didn't cover the ibmq/ *.py files.
I believe adding the __init__.py files allowed me to define the line target as
pylint -rn --disable='C0103, W0621, E0611, E0401' examples,
instead of individually specifying the *.py files.
I think I went for this implementation because if other example subdirectories get added in future, it would not be needed to add an extra dir/*.py to the lint.

[1ucian0]

Hmm... I think pylint is recursive in all the subdirectories by default. But I did not check it.

[1ucian0]

Could you give this another look @dhruvbhq? Would something like this make it without the __init__.py?

pylint -rn --disable='C0103, C0114, W0621' examples/python/*.py examples/python/ibmq/*.py

[jakelishman]

Getting the linter running on all the scripts would be nice - they don't change much, but they should reflect decent Python practices at least.

Making things packages in Python has some unintended consequences, and I'm not sure it's really the right way to go here. The examples scripts are all logically separate scripts, and probably should be linted as such - if pylint won't recurse into a non-package directory on its own, it's better to do it in the shell than making a dummy package. What Luciano wrote about just specifying the directories manually is the right way here - we very rarely add new scripts so it's not a big deal to need to update a couple more lines, and this avoids the unintended consequences of creating packages.

[jakelishman]

The examples directory isn't a Python package - it's just a collection of scripts - so it shouldn't be made into a package. Doing things like this has surprising effects (mostly this is Python's fault), because editable (developer) installs of Terra will now end up making examples an importable package whenever you open a Python interpreter. That means you wouldn't be able to access a package with that actual name any more (for example https://pypi.org/project/examples/).

(There are ways in our repository structure we can mitigate this, but really the issue is that this shouldn't be a package.)

[jakelishman]

Similar to above, this shouldn't be in a package, because the examples aren't modules, they're scripts.

[jakelishman]

With more things being added here, it would be nice to switch to using the verbose names - I can't tell at a glance what's being disabled here.

[dhruvbhq]

Hi,
Ah, I see. Those are some interesting consequences which I was unaware of. I will try to work on it as soon as I am able to.

[jakelishman]

Hi there - sorry to come back like this, but with #8080 (and general Qiskit direction), we're going to be removing the IBMQ examples from the Terra repository because qiskit-ibmq-provider is going to be deprecated in favour of a new package called qiskit-ibm-provider (ibm not ibmq). We won't be replacing these examples, so covering them for lint isn't necessary any more.

Thanks for the interest in contributing, though, and sorry it came down like this. If you're interested in finding something else, please have a look at our issues tagged "good first issue" or "help wanted".