Add type hints to gates and QuantumCircuit #6831
Conversation
This adds full type hints to all public function entry points in
QuantumCircuit. This will not cause quantumcircuit.py to pass a mypy
check yet; there are various idioms used within the file which are not
statically type-safe (nor, in some cases, dynamically type safe in the
sense that we sometimes rely on mismatched types to throw exceptions).
These include anything which takes the `inplace` argument, since
`inplace=True` versions do not return, which influences the out types to
Optional["QuantumCircuit"]
This then means that methods using these functions (e.g.
`QuantumCircuit.__add__`) become unsafe; even though they use the
default `inplace=False`, subclasses could override this while still
maintaining type safety, and so the operation is not safe.
This patch makes no attempt to modify the behaviour of these
non-type-safe functions, only to classify what the current types are.
This completes the standard-library gate documentation overhaul tracked by Qiskit#3705, and mostly done in Qiskit#4017, by adding type hints to the initializers. It also adds the missing `label` option to the iSWAP, R, RXX, RYY, RZX and RZZ gates, to bring them up to parity with the other gates, tracked in Qiskit#6780.
This only adds short documentation to the docstrings of the gate methods (for example `QuantumCircuit.x`) about the parameters and the return values. It does not currently import the matrix representations into the docstrings themselves, because the gate classes include those. The expectation is that you would see the docstring when running interactively, and even in Jupyter, this typically does not include displaying maths. The matrix form is more useful when looking at the online Sphinx documentation, where the cross-reference gate link will work more easily.
|
Oh yeah, in other details: this leaves the fractured nature of the |
Python 3.6 doesn't allow assigning to the __doc__ field of the `typing` types, so as long as we support it, we can't do that.
|
Looks good. Any reason you didn't bring |
The previous commit stopped `QuantumCircuit.measure` from being monkey-patched in by `qiskit/circuit/measure.py`, but the similar `QuantumCircuit.reset` operation was overlooked. This adds it in for consistency.
|
@levbishop: no good reason - I suspect I noticed that There are still 3 monkey-patched functions in the circuit library ( |
|
Oh, I should highlight: the hints I've added should all be correct (I believe), but there's a few places where the |
|
For now lets just make any added hints correct, since that is uncontroversial. |
jakelishman
added
automerge
Changelog: API Change
Summary
This is pretty much all documentation changes, except that it also moves the definition of
QuantumCircuit.measureintoquantumcircuit.pyrather than monkey-patching it frommeasure.py. This makes it consistent with other instruction definitions, and made it easier to access theQubitSpecifierandClbitSpecifiertype aliases.Add type hints to QuantumCircuit
This adds full type hints to all public function entry points in
QuantumCircuit. This will not cause quantumcircuit.py to pass a mypy
check yet; there are various idioms used within the file which are not
statically type-safe (nor, in some cases, dynamically type safe in the
sense that we sometimes rely on mismatched types to throw exceptions).
These include anything which takes the
inplaceargument, sinceinplace=Trueversions do not return, which influences the out types toOptional["QuantumCircuit"]
This then means that methods using these functions (e.g.
QuantumCircuit.__add__) become unsafe; even though they use thedefault
inplace=False, subclasses could override this while stillmaintaining type safety, and so the operation is not safe.
This patch makes no attempt to modify the behaviour of these
non-type-safe functions, only to classify what the current types are.
Add type hints and label to all standard gate classes
This completes the standard-library gate documentation overhaul tracked
by #3705, and mostly done in #4017, by adding type hints to the
initializers.
It also adds the missing
labeloption to the iSWAP, R, RXX, RYY, RZXand RZZ gates, to bring them up to parity with the other gates, tracked
in #6780.
Add parameters to QuantumCircuit gate docstrings
This only adds short documentation to the docstrings of the gate methods
(for example
QuantumCircuit.x) about the parameters and the returnvalues. It does not currently import the matrix representations into
the docstrings themselves, because the gate classes include those. The
expectation is that you would see the docstring when running
interactively, and even in Jupyter, this typically does not include
displaying maths. The matrix form is more useful when looking at the
online Sphinx documentation, where the cross-reference gate link will
work more easily.
Details and comments
Fix #3705
Fix #6780
I didn't pull the actual matrix definitions into the QuantumCircuit docstrings, because I think they'll add a lot of unreadable noise to the points where you'd actually see them most commonly - in the Jupyter/IDE popups for help and completions. These are text-based, and so don't really show maths in the most part. The only places you expect to see the maths are in the Spinx websites, where the links that are already in the docstring will work anyway.
There is a slight nuisance at the moment in that neither
sphinx.ext.napoleonnorsphinx_autodoc_typehintsquite handle cross-referencing the typehints in the docstrings properly, but this is something we could fix externally.There are a few parts in
QuantumCircuitwhere we're not doing things fully type-safely, and a couple of places where we do it in such a way that mypy can't statically analysise it. I haven't attempted to fix any of this, since that can be done elsewhere.