From 0658e22cc38c1ca82790b54756099e57bb2ab52e Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Sun, 15 Sep 2019 19:44:59 -0500
Subject: [PATCH 01/25] Add type annotations to the gates module

Resolves #988
---
 pyquil/gates.py    | 155 ++++++++++++++++++++++++++++-----------------
 pyquil/quilatom.py |  61 ++++++++++--------
 2 files changed, 131 insertions(+), 85 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index fad123a48..84c39d49a 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -14,19 +14,28 @@
 #    limitations under the License.
 ##############################################################################
 from warnings import warn
-from typing import Callable, Dict
-from pyquil.quilatom import unpack_qubit, unpack_classical_reg, MemoryReference, Addr, Qubit
-from pyquil.quilbase import (Measurement, Gate, Wait, Reset, Halt, Nop,
+from typing import Any, Callable, Dict, Optional, Tuple, Union
+
+from pyquil.quilatom import (Addr, MemoryReference, MemoryReferenceDesignator, Parameter, Qubit,
+                             QubitDesignator, QubitPlaceholder, unpack_classical_reg, unpack_qubit)
+from pyquil.quilbase import (AbstractInstruction, Gate, Halt, Reset, ResetQubit, Measurement, Nop,
+                             Wait,
                              ClassicalNeg, ClassicalNot,
                              ClassicalAnd, ClassicalInclusiveOr, ClassicalExclusiveOr,
                              ClassicalEqual, ClassicalGreaterEqual, ClassicalGreaterThan,
                              ClassicalLessEqual, ClassicalLessThan,
                              ClassicalMove, ClassicalExchange, ClassicalConvert,
                              ClassicalLoad, ClassicalStore,
-                             ClassicalAdd, ClassicalSub, ClassicalMul, ClassicalDiv, ResetQubit)
+                             ClassicalAdd, ClassicalSub, ClassicalMul, ClassicalDiv)
+
 
+MemoryReferenceOrImmediateValue = Union[MemoryReferenceDesignator, int, float]
+MemoryReferenceOrImmediateInt = Union[MemoryReferenceDesignator, int]
+GateParameter = Union[Parameter, MemoryReference, int, float, complex]
 
-def unpack_reg_val_pair(classical_reg1, classical_reg2):
+def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
+                        classical_reg2: MemoryReferenceOrImmediateValue) \
+                        -> Tuple[MemoryReference, MemoryReferenceOrImmediateValue]:
     """
     Helper function for typechecking / type-coercing arguments to constructors for binary classical operators.
 
@@ -36,14 +45,15 @@ def unpack_reg_val_pair(classical_reg1, classical_reg2):
     """
     left = unpack_classical_reg(classical_reg1)
     if isinstance(classical_reg2, int) or isinstance(classical_reg2, float):
-        right = classical_reg2
-    else:
-        right = unpack_classical_reg(classical_reg2)
-
-    return left, right
+        return left, classical_reg2
+    return left, unpack_classical_reg(classical_reg2)
 
 
-def prepare_ternary_operands(classical_reg1, classical_reg2, classical_reg3):
+def prepare_ternary_operands(classical_reg1: MemoryReferenceDesignator,
+                             classical_reg2: MemoryReferenceDesignator,
+                             # TODO:(appleby) why doesn't prepare_ternary_operands allow floats for classical_reg3
+                             classical_reg3: MemoryReferenceOrImmediateInt) \
+                             -> Tuple[MemoryReference, MemoryReference, MemoryReferenceOrImmediateInt]:
     """
     Helper function for typechecking / type-coercing arguments to constructors for ternary classical operators.
 
@@ -64,7 +74,7 @@ def prepare_ternary_operands(classical_reg1, classical_reg2, classical_reg3):
     return classical_reg1, classical_reg2, classical_reg3
 
 
-def I(qubit):
+def I(qubit: QubitDesignator) -> Gate:
     """Produces the I identity gate::
 
         I = [1, 0]
@@ -81,7 +91,7 @@ def I(qubit):
     return Gate(name="I", params=[], qubits=[unpack_qubit(qubit)])
 
 
-def X(qubit):
+def X(qubit: QubitDesignator) -> Gate:
     """Produces the X ("NOT") gate::
 
         X = [[0, 1],
@@ -95,7 +105,7 @@ def X(qubit):
     return Gate(name="X", params=[], qubits=[unpack_qubit(qubit)])
 
 
-def Y(qubit):
+def Y(qubit: QubitDesignator) -> Gate:
     """Produces the Y gate::
 
         Y = [[0, 0 - 1j],
@@ -109,7 +119,7 @@ def Y(qubit):
     return Gate(name="Y", params=[], qubits=[unpack_qubit(qubit)])
 
 
-def Z(qubit):
+def Z(qubit: QubitDesignator) -> Gate:
     """Produces the Z gate::
 
         Z = [[1,  0],
@@ -123,7 +133,7 @@ def Z(qubit):
     return Gate(name="Z", params=[], qubits=[unpack_qubit(qubit)])
 
 
-def H(qubit):
+def H(qubit: QubitDesignator) -> Gate:
     """Produces the Hadamard gate::
 
         H = (1 / sqrt(2)) * [[1,  1],
@@ -137,7 +147,7 @@ def H(qubit):
     return Gate(name="H", params=[], qubits=[unpack_qubit(qubit)])
 
 
-def S(qubit):
+def S(qubit: QubitDesignator) -> Gate:
     """Produces the S gate::
 
         S = [[1, 0],
@@ -151,7 +161,7 @@ def S(qubit):
     return Gate(name="S", params=[], qubits=[unpack_qubit(qubit)])
 
 
-def T(qubit):
+def T(qubit: QubitDesignator) -> Gate:
     """Produces the T gate::
 
         T = [[1, 0],
@@ -165,7 +175,7 @@ def T(qubit):
     return Gate(name="T", params=[], qubits=[unpack_qubit(qubit)])
 
 
-def RX(angle, qubit):
+def RX(angle: GateParameter, qubit: QubitDesignator) -> Gate:
     """Produces the RX gate::
 
         RX(phi) = [[cos(phi / 2), -1j * sin(phi / 2)],
@@ -180,7 +190,7 @@ def RX(angle, qubit):
     return Gate(name="RX", params=[angle], qubits=[unpack_qubit(qubit)])
 
 
-def RY(angle, qubit):
+def RY(angle: GateParameter, qubit: QubitDesignator) -> Gate:
     """Produces the RY gate::
 
         RY(phi) = [[cos(phi / 2), -sin(phi / 2)],
@@ -195,7 +205,7 @@ def RY(angle, qubit):
     return Gate(name="RY", params=[angle], qubits=[unpack_qubit(qubit)])
 
 
-def RZ(angle, qubit):
+def RZ(angle: GateParameter, qubit: QubitDesignator) -> Gate:
     """Produces the RZ gate::
 
         RZ(phi) = [[cos(phi / 2) - 1j * sin(phi / 2), 0]
@@ -210,7 +220,7 @@ def RZ(angle, qubit):
     return Gate(name="RZ", params=[angle], qubits=[unpack_qubit(qubit)])
 
 
-def PHASE(angle, qubit):
+def PHASE(angle: GateParameter, qubit: QubitDesignator) -> Gate:
     """Produces the PHASE gate::
 
         PHASE(phi) = [[1, 0],
@@ -225,7 +235,7 @@ def PHASE(angle, qubit):
     return Gate(name="PHASE", params=[angle], qubits=[unpack_qubit(qubit)])
 
 
-def CZ(control, target):
+def CZ(control: QubitDesignator, target: QubitDesignator) -> Gate:
     """Produces a controlled-Z gate::
 
         CZ = [[1, 0, 0,  0],
@@ -244,7 +254,7 @@ def CZ(control, target):
     return Gate(name="CZ", params=[], qubits=[unpack_qubit(q) for q in (control, target)])
 
 
-def CNOT(control, target):
+def CNOT(control: QubitDesignator, target: QubitDesignator) -> Gate:
     """Produces a controlled-NOT (controlled-X) gate::
 
         CNOT = [[1, 0, 0, 0],
@@ -262,7 +272,7 @@ def CNOT(control, target):
     return Gate(name="CNOT", params=[], qubits=[unpack_qubit(q) for q in (control, target)])
 
 
-def CCNOT(control1, control2, target):
+def CCNOT(control1: QubitDesignator, control2: QubitDesignator, target: QubitDesignator) -> Gate:
     """Produces a doubly-controlled NOT gate::
 
         CCNOT = [[1, 0, 0, 0, 0, 0, 0, 0],
@@ -287,7 +297,7 @@ def CCNOT(control1, control2, target):
     return Gate(name="CCNOT", params=[], qubits=qubits)
 
 
-def CPHASE00(angle, control, target):
+def CPHASE00(angle: GateParameter, control: QubitDesignator, target: QubitDesignator) -> Gate:
     """Produces a controlled-phase gate that phases the ``|00>`` state::
 
         CPHASE00(phi) = diag([exp(1j * phi), 1, 1, 1])
@@ -304,7 +314,7 @@ def CPHASE00(angle, control, target):
     return Gate(name="CPHASE00", params=[angle], qubits=qubits)
 
 
-def CPHASE01(angle, control, target):
+def CPHASE01(angle: GateParameter, control: QubitDesignator, target: QubitDesignator) -> Gate:
     """Produces a controlled-phase gate that phases the ``|01>`` state::
 
         CPHASE01(phi) = diag([1.0, exp(1j * phi), 1.0, 1.0])
@@ -322,7 +332,7 @@ def CPHASE01(angle, control, target):
     return Gate(name="CPHASE01", params=[angle], qubits=qubits)
 
 
-def CPHASE10(angle, control, target):
+def CPHASE10(angle: GateParameter, control: QubitDesignator, target: QubitDesignator) -> Gate:
     """Produces a controlled-phase gate that phases the ``|10>`` state::
 
         CPHASE10(phi) = diag([1, 1, exp(1j * phi), 1])
@@ -340,7 +350,7 @@ def CPHASE10(angle, control, target):
     return Gate(name="CPHASE10", params=[angle], qubits=qubits)
 
 
-def CPHASE(angle, control, target):
+def CPHASE(angle: GateParameter, control: QubitDesignator, target: QubitDesignator) -> Gate:
     """Produces a controlled-phase instruction::
 
         CPHASE(phi) = diag([1, 1, 1, exp(1j * phi)])
@@ -360,7 +370,7 @@ def CPHASE(angle, control, target):
     return Gate(name="CPHASE", params=[angle], qubits=qubits)
 
 
-def SWAP(q1, q2):
+def SWAP(q1: QubitDesignator, q2: QubitDesignator) -> Gate:
     """Produces a SWAP gate which swaps the state of two qubits::
 
         SWAP = [[1, 0, 0, 0],
@@ -376,7 +386,7 @@ def SWAP(q1, q2):
     return Gate(name="SWAP", params=[], qubits=[unpack_qubit(q) for q in (q1, q2)])
 
 
-def CSWAP(control, target_1, target_2):
+def CSWAP(control: QubitDesignator, target_1: QubitDesignator, target_2: QubitDesignator) -> Gate:
     """Produces a controlled-SWAP gate. This gate conditionally swaps the state of two qubits::
 
         CSWAP = [[1, 0, 0, 0, 0, 0, 0, 0],
@@ -398,7 +408,7 @@ def CSWAP(control, target_1, target_2):
     return Gate(name="CSWAP", params=[], qubits=qubits)
 
 
-def ISWAP(q1, q2):
+def ISWAP(q1: QubitDesignator, q2: QubitDesignator) -> Gate:
     """Produces an ISWAP gate::
 
         ISWAP = [[1, 0,  0,  0],
@@ -416,7 +426,7 @@ def ISWAP(q1, q2):
     return Gate(name="ISWAP", params=[], qubits=[unpack_qubit(q) for q in (q1, q2)])
 
 
-def PSWAP(angle, q1, q2):
+def PSWAP(angle: GateParameter, q1: QubitDesignator, q2: QubitDesignator) -> Gate:
     """Produces a parameterized SWAP gate::
 
         PSWAP(phi) = [[1, 0,             0,             0],
@@ -443,11 +453,11 @@ def PSWAP(angle, q1, q2):
 """
 
 
-def RESET(qubit_index=None):
+def RESET(qubit_index: Optional[QubitDesignator] = None) -> Union[Reset, ResetQubit]:
     """
     Reset all qubits or just one specific qubit.
 
-    :param Optional[Union[integer_types, Qubit, QubitPlaceholder]] qubit_index: The qubit to reset.
+    :param Optional[QubitDesignator] qubit_index: The qubit to reset.
         This can be a qubit's index, a Qubit, or a QubitPlaceholder.
         If None, reset all qubits.
     :returns: A Reset or ResetQubit Quil AST expression corresponding to a global or targeted
@@ -475,7 +485,7 @@ def RESET(qubit_index=None):
 """
 
 
-def MEASURE(qubit, classical_reg):
+def MEASURE(qubit: QubitDesignator, classical_reg: Optional[MemoryReferenceDesignator]) -> Measurement:
     """
     Produce a MEASURE instruction.
 
@@ -495,7 +505,7 @@ def MEASURE(qubit, classical_reg):
     return Measurement(qubit, address)
 
 
-def TRUE(classical_reg):
+def TRUE(classical_reg: Union[MemoryReference, int]) -> ClassicalMove:
     """
     Produce a TRUE instruction.
 
@@ -508,7 +518,7 @@ def TRUE(classical_reg):
     return MOVE(classical_reg, 1)
 
 
-def FALSE(classical_reg):
+def FALSE(classical_reg: Union[MemoryReference, int]) -> ClassicalMove:
     """
     Produce a FALSE instruction.
 
@@ -521,7 +531,7 @@ def FALSE(classical_reg):
     return MOVE(classical_reg, 0)
 
 
-def NEG(classical_reg):
+def NEG(classical_reg: MemoryReferenceDesignator) -> ClassicalNeg:
     """
     Produce a NEG instruction.
 
@@ -531,7 +541,7 @@ def NEG(classical_reg):
     return ClassicalNeg(unpack_classical_reg(classical_reg))
 
 
-def NOT(classical_reg):
+def NOT(classical_reg: MemoryReferenceDesignator) -> ClassicalNot:
     """
     Produce a NOT instruction.
 
@@ -541,7 +551,8 @@ def NOT(classical_reg):
     return ClassicalNot(unpack_classical_reg(classical_reg))
 
 
-def AND(classical_reg1, classical_reg2):
+def AND(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceOrImmediateValue) \
+    -> ClassicalAnd:
     """
     Produce an AND instruction.
 
@@ -555,7 +566,8 @@ def AND(classical_reg1, classical_reg2):
     return ClassicalAnd(left, right)
 
 
-def OR(classical_reg1, classical_reg2):
+def OR(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceDesignator) \
+    -> ClassicalInclusiveOr:
     """
     Produce an OR instruction.
 
@@ -569,7 +581,8 @@ def OR(classical_reg1, classical_reg2):
     return IOR(classical_reg2, classical_reg1)
 
 
-def IOR(classical_reg1, classical_reg2):
+def IOR(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceOrImmediateValue) \
+    -> ClassicalInclusiveOr:
     """
     Produce an inclusive OR instruction.
 
@@ -581,7 +594,8 @@ def IOR(classical_reg1, classical_reg2):
     return ClassicalInclusiveOr(left, right)
 
 
-def XOR(classical_reg1, classical_reg2):
+def XOR(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceOrImmediateValue) \
+    -> ClassicalExclusiveOr:
     """
     Produce an exclusive OR instruction.
 
@@ -593,7 +607,8 @@ def XOR(classical_reg1, classical_reg2):
     return ClassicalExclusiveOr(left, right)
 
 
-def MOVE(classical_reg1, classical_reg2):
+def MOVE(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceOrImmediateValue) \
+    -> ClassicalMove:
     """
     Produce a MOVE instruction.
 
@@ -605,7 +620,8 @@ def MOVE(classical_reg1, classical_reg2):
     return ClassicalMove(left, right)
 
 
-def EXCHANGE(classical_reg1, classical_reg2):
+def EXCHANGE(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceDesignator) \
+    -> ClassicalExchange:
     """
     Produce an EXCHANGE instruction.
 
@@ -618,7 +634,9 @@ def EXCHANGE(classical_reg1, classical_reg2):
     return ClassicalExchange(left, right)
 
 
-def LOAD(target_reg, region_name, offset_reg):
+def LOAD(target_reg: MemoryReferenceDesignator,
+         region_name: str,
+         offset_reg: MemoryReferenceDesignator) -> ClassicalLoad:
     """
     Produce a LOAD instruction.
 
@@ -630,7 +648,11 @@ def LOAD(target_reg, region_name, offset_reg):
     return ClassicalLoad(unpack_classical_reg(target_reg), region_name, unpack_classical_reg(offset_reg))
 
 
-def STORE(region_name, offset_reg, source):
+# TODO:(appleby) Docstring wrong here? ClassicalStore's __init__ will throw an exception if either
+# of the last two args are not MemoryReferences. Perhaps the comment should say that offset_reg can
+# be either MemoryReference or constant (i.e. MemoryReferenceDesignator)?
+def STORE(region_name: str, offset_reg: MemoryReferenceDesignator, source: MemoryReference) \
+    -> ClassicalStore:
     """
     Produce a STORE instruction.
 
@@ -644,7 +666,8 @@ def STORE(region_name, offset_reg, source):
     return ClassicalStore(region_name, unpack_classical_reg(offset_reg), source)
 
 
-def CONVERT(classical_reg1, classical_reg2):
+# TODO:(appleby) should this take 2 MemoryReferenceDesignators and call unpack_classical_reg on them?
+def CONVERT(classical_reg1: MemoryReference, classical_reg2: MemoryReference) -> ClassicalConvert:
     """
     Produce a CONVERT instruction.
 
@@ -656,7 +679,8 @@ def CONVERT(classical_reg1, classical_reg2):
                             unpack_classical_reg(classical_reg2))
 
 
-def ADD(classical_reg, right):
+def ADD(classical_reg: MemoryReferenceDesignator, right: MemoryReferenceOrImmediateValue) \
+    -> ClassicalAdd:
     """
     Produce an ADD instruction.
 
@@ -668,7 +692,8 @@ def ADD(classical_reg, right):
     return ClassicalAdd(left, right)
 
 
-def SUB(classical_reg, right):
+def SUB(classical_reg: MemoryReferenceDesignator, right: MemoryReferenceOrImmediateValue) \
+    -> ClassicalSub:
     """
     Produce a SUB instruction.
 
@@ -680,7 +705,8 @@ def SUB(classical_reg, right):
     return ClassicalSub(left, right)
 
 
-def MUL(classical_reg, right):
+def MUL(classical_reg: MemoryReferenceDesignator, right: MemoryReferenceOrImmediateValue) \
+    -> ClassicalMul:
     """
     Produce a MUL instruction.
 
@@ -692,7 +718,8 @@ def MUL(classical_reg, right):
     return ClassicalMul(left, right)
 
 
-def DIV(classical_reg, right):
+def DIV(classical_reg: MemoryReferenceDesignator, right: MemoryReferenceOrImmediateValue) \
+    -> ClassicalDiv:
     """
     Produce an DIV instruction.
 
@@ -704,7 +731,9 @@ def DIV(classical_reg, right):
     return ClassicalDiv(left, right)
 
 
-def EQ(classical_reg1, classical_reg2, classical_reg3):
+def EQ(classical_reg1: MemoryReferenceDesignator,
+       classical_reg2: MemoryReferenceDesignator,
+       classical_reg3: MemoryReferenceOrImmediateInt) -> ClassicalEqual:
     """
     Produce an EQ instruction.
 
@@ -720,7 +749,9 @@ def EQ(classical_reg1, classical_reg2, classical_reg3):
     return ClassicalEqual(classical_reg1, classical_reg2, classical_reg3)
 
 
-def LT(classical_reg1, classical_reg2, classical_reg3):
+def LT(classical_reg1: MemoryReferenceDesignator,
+       classical_reg2: MemoryReferenceDesignator,
+       classical_reg3: MemoryReferenceOrImmediateInt) -> ClassicalLessThan:
     """
     Produce an LT instruction.
 
@@ -735,7 +766,9 @@ def LT(classical_reg1, classical_reg2, classical_reg3):
     return ClassicalLessThan(classical_reg1, classical_reg2, classical_reg3)
 
 
-def LE(classical_reg1, classical_reg2, classical_reg3):
+def LE(classical_reg1: MemoryReferenceDesignator,
+       classical_reg2: MemoryReferenceDesignator,
+       classical_reg3: MemoryReferenceOrImmediateInt) -> ClassicalLessEqual:
     """
     Produce an LE instruction.
 
@@ -750,7 +783,9 @@ def LE(classical_reg1, classical_reg2, classical_reg3):
     return ClassicalLessEqual(classical_reg1, classical_reg2, classical_reg3)
 
 
-def GT(classical_reg1, classical_reg2, classical_reg3):
+def GT(classical_reg1: MemoryReferenceDesignator,
+       classical_reg2: MemoryReferenceDesignator,
+       classical_reg3: MemoryReferenceOrImmediateInt) -> ClassicalGreaterThan:
     """
     Produce an GT instruction.
 
@@ -765,7 +800,9 @@ def GT(classical_reg1, classical_reg2, classical_reg3):
     return ClassicalGreaterThan(classical_reg1, classical_reg2, classical_reg3)
 
 
-def GE(classical_reg1, classical_reg2, classical_reg3):
+def GE(classical_reg1: MemoryReferenceDesignator,
+       classical_reg2: MemoryReferenceDesignator,
+       classical_reg3: MemoryReferenceOrImmediateInt) -> ClassicalGreaterEqual:
     """
     Produce an GE instruction.
 
@@ -812,7 +849,7 @@ def GE(classical_reg1, classical_reg2, classical_reg3):
 Alias for the above dictionary of quantum gates.
 """
 
-STANDARD_INSTRUCTIONS = {
+STANDARD_INSTRUCTIONS: Dict[str, Union[AbstractInstruction, Callable[..., AbstractInstruction]]] = {
     'WAIT': WAIT,
     'RESET': RESET,
     'NOP': NOP,
diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index db019157b..094e6d76e 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -16,6 +16,7 @@
 import numpy as np
 from warnings import warn
 from fractions import Fraction
+from typing import List, Tuple, Union
 
 
 class QuilAtom(object):
@@ -103,7 +104,10 @@ def register(cls, n):
         return [cls() for _ in range(n)]
 
 
-def unpack_qubit(qubit):
+QubitDesignator = Union[Qubit, QubitPlaceholder, int]
+
+
+def unpack_qubit(qubit: QubitDesignator) -> Union[Qubit, QubitPlaceholder]:
     """
     Get a qubit from an object.
 
@@ -120,31 +124,6 @@ def unpack_qubit(qubit):
         raise TypeError("qubit should be an int or Qubit instance")
 
 
-def unpack_classical_reg(c):
-    """
-    Get the address for a classical register.
-
-    :param c: A list of length 2, a pair, a string (to be interpreted as name[0]), or a MemoryReference.
-    :return: The address as a MemoryReference.
-    """
-    if isinstance(c, list) or isinstance(c, tuple):
-        if len(c) > 2 or len(c) == 0:
-            raise ValueError("if c is a list/tuple, it should be of length <= 2")
-        if len(c) == 1:
-            c = (c[0], 0)
-        if not isinstance(c[0], str):
-            raise ValueError("if c is a list/tuple, its first member should be a string")
-        if not isinstance(c[1], int):
-            raise ValueError("if c is a list/tuple, its second member should be an int")
-        return MemoryReference(c[0], c[1])
-    if isinstance(c, MemoryReference):
-        return c
-    elif isinstance(c, str):
-        return MemoryReference(c, 0)
-    else:
-        raise TypeError("c should be a list of length 2, a pair, a string, or a MemoryReference")
-
-
 class Label(QuilAtom):
     """
     Representation of a label.
@@ -634,3 +613,33 @@ def __init__(self, value):
         if not isinstance(value, int) or value < 0:
             raise TypeError("Addr value must be a non-negative int")
         super(Addr, self).__init__("ro", offset=value, declared_size=None)
+
+
+# Like the Tuple, the List must be length 2, where the first item is a string and the second is an
+# int.
+MemoryReferenceDesignator = Union[MemoryReference, str, Tuple[str, int], List[Union[str, int]]]
+
+
+def unpack_classical_reg(c: MemoryReferenceDesignator) -> MemoryReference:
+    """
+    Get the address for a classical register.
+
+    :param c: A list of length 2, a pair, a string (to be interpreted as name[0]), or a MemoryReference.
+    :return: The address as a MemoryReference.
+    """
+    if isinstance(c, list) or isinstance(c, tuple):
+        if len(c) > 2 or len(c) == 0:
+            raise ValueError("if c is a list/tuple, it should be of length <= 2")
+        if len(c) == 1:
+            c = (c[0], 0)
+        if not isinstance(c[0], str):
+            raise ValueError("if c is a list/tuple, its first member should be a string")
+        if not isinstance(c[1], int):
+            raise ValueError("if c is a list/tuple, its second member should be an int")
+        return MemoryReference(c[0], c[1])
+    if isinstance(c, MemoryReference):
+        return c
+    elif isinstance(c, str):
+        return MemoryReference(c, 0)
+    else:
+        raise TypeError("c should be a list of length 2, a pair, a string, or a MemoryReference")

From 0d7de29df1444c6dccc2df43cfd5567c997259f9 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Mon, 16 Sep 2019 10:09:26 -0500
Subject: [PATCH 02/25] Add type annotations to the quilatom module

---
 pyquil/gates.py    |   2 +
 pyquil/quilatom.py | 251 +++++++++++++++++++++++----------------------
 2 files changed, 132 insertions(+), 121 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index 84c39d49a..0a55dc3e7 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -31,8 +31,10 @@
 
 MemoryReferenceOrImmediateValue = Union[MemoryReferenceDesignator, int, float]
 MemoryReferenceOrImmediateInt = Union[MemoryReferenceDesignator, int]
+# TODO:(appleby) Should this type just be quilatom.ParameterDesignator?
 GateParameter = Union[Parameter, MemoryReference, int, float, complex]
 
+
 def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
                         classical_reg2: MemoryReferenceOrImmediateValue) \
                         -> Tuple[MemoryReference, MemoryReferenceOrImmediateValue]:
diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index 094e6d76e..f46635db8 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -16,7 +16,7 @@
 import numpy as np
 from warnings import warn
 from fractions import Fraction
-from typing import List, Tuple, Union
+from typing import Any, Callable, ClassVar, Dict, List, Optional, Set, Tuple, Union
 
 
 class QuilAtom(object):
@@ -33,7 +33,7 @@ def __str__(self):
     def __eq__(self, other):
         raise NotImplementedError()
 
-    def __ne__(self, other):
+    def __ne__(self, other: object) -> bool:
         return not self.__eq__(other)
 
     def __hash__(self):
@@ -47,24 +47,24 @@ class Qubit(QuilAtom):
     :param int index: Index of the qubit.
     """
 
-    def __init__(self, index):
+    def __init__(self, index: int) -> None:
         if not (isinstance(index, int) and index >= 0):
             raise TypeError("Addr index must be a non-negative int")
         self.index = index
 
-    def out(self):
+    def out(self) -> str:
         return str(self.index)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self.index)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<Qubit {0}>".format(self.index)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.index)
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return isinstance(other, Qubit) and other.index == self.index
 
 
@@ -72,20 +72,20 @@ class QubitPlaceholder(QuilAtom):
     def out(self):
         raise RuntimeError("Qubit {} has not been assigned an index".format(self))
 
-    def __str__(self):
+    def __str__(self) -> str:
         return "q{}".format(id(self))
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<QubitPlaceholder {}>".format(id(self))
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(id(self))
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return isinstance(other, QubitPlaceholder) and id(other) == id(self)
 
     @classmethod
-    def register(cls, n):
+    def register(cls, n: int) -> List['QubitPlaceholder']:
         """Return a 'register' of ``n`` QubitPlaceholders.
 
         >>> qs = QubitPlaceholder.register(8) # a qubyte
@@ -124,6 +124,35 @@ def unpack_qubit(qubit: QubitDesignator) -> Union[Qubit, QubitPlaceholder]:
         raise TypeError("qubit should be an int or Qubit instance")
 
 
+# Like the Tuple, the List must be length 2, where the first item is a string and the second an int.
+MemoryReferenceDesignator = Union['MemoryReference', Tuple[str, int], List, str]
+
+
+def unpack_classical_reg(c: MemoryReferenceDesignator) -> 'MemoryReference':
+    """
+    Get the address for a classical register.
+
+    :param c: A list of length 2, a pair, a string (to be interpreted as name[0]), or a MemoryReference.
+    :return: The address as a MemoryReference.
+    """
+    if isinstance(c, list) or isinstance(c, tuple):
+        if len(c) > 2 or len(c) == 0:
+            raise ValueError("if c is a list/tuple, it should be of length <= 2")
+        if len(c) == 1:
+            c = (c[0], 0)
+        if not isinstance(c[0], str):
+            raise ValueError("if c is a list/tuple, its first member should be a string")
+        if not isinstance(c[1], int):
+            raise ValueError("if c is a list/tuple, its second member should be an int")
+        return MemoryReference(c[0], c[1])
+    if isinstance(c, MemoryReference):
+        return c
+    elif isinstance(c, str):
+        return MemoryReference(c, 0)
+    else:
+        raise TypeError("c should be a list of length 2, a pair, a string, or a MemoryReference")
+
+
 class Label(QuilAtom):
     """
     Representation of a label.
@@ -131,51 +160,54 @@ class Label(QuilAtom):
     :param string label_name: The label name.
     """
 
-    def __init__(self, label_name):
+    def __init__(self, label_name: str) -> None:
         self.name = label_name
 
-    def out(self):
+    def out(self) -> str:
         return "@{name}".format(name=self.name)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return "@{name}".format(name=self.name)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<Label {0}>".format(repr(self.name))
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return isinstance(other, Label) and other.name == self.name
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.name)
 
 
 class LabelPlaceholder(QuilAtom):
-    def __init__(self, prefix="L"):
+    def __init__(self, prefix: str = "L") -> None:
         self.prefix = prefix
 
     def out(self):
         raise RuntimeError("Label has not been assigned a name")
 
-    def __str__(self):
+    def __str__(self) -> str:
         return repr(self)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<LabelPlaceholder {} {}>".format(self.prefix, id(self))
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return isinstance(other, LabelPlaceholder) and id(other) == id(self)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(id(self))
 
 
-def format_parameter(element):
+ParameterDesignator = Union['Expression', 'MemoryReference', np.int_, int, float, complex]
+
+
+def format_parameter(element: ParameterDesignator) -> str:
     """
     Formats a particular parameter. Essentially the same as built-in formatting except using 'i' instead of 'j' for
     the imaginary number.
 
-    :param element: {int, float, long, complex, Parameter} Formats a parameter for Quil output.
+    :param element: {int, float, complex, Parameter, MemoryReference, Expression} Formats a parameter for Quil output.
     """
     if isinstance(element, int) or isinstance(element, np.int_):
         return repr(element)
@@ -209,11 +241,13 @@ def format_parameter(element):
         return str(element)
     elif isinstance(element, Expression):
         return _expression_to_string(element)
-    elif isinstance(element, MemoryReference):
-        return element.out()
     assert False, "Invalid parameter: %r" % element
 
 
+ExpressionValue = Union[int, float]
+ExpressionOrValue = Union['Expression', ExpressionValue]
+
+
 class Expression(object):
     """
     Expression involving some unbound parameters. Parameters in Quil are represented as a label like '%x' for the
@@ -223,54 +257,57 @@ class Expression(object):
 
     This class overrides all the Python operators that are supported by Quil.
     """
-    def __str__(self):
+    def __str__(self) -> str:
         return _expression_to_string(self)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return str(self.__class__.__name__) + '(' + ','.join(map(repr, self.__dict__.values())) + ')'
 
-    def __add__(self, other):
+    def __add__(self, other: ExpressionOrValue) -> 'Add':
         return Add(self, other)
 
-    def __radd__(self, other):
+    def __radd__(self, other: ExpressionOrValue) -> 'Add':
         return Add(other, self)
 
-    def __sub__(self, other):
+    def __sub__(self, other: ExpressionOrValue) -> 'Sub':
         return Sub(self, other)
 
-    def __rsub__(self, other):
+    def __rsub__(self, other: ExpressionOrValue) -> 'Sub':
         return Sub(other, self)
 
-    def __mul__(self, other):
+    def __mul__(self, other: ExpressionOrValue) -> 'Mul':
         return Mul(self, other)
 
-    def __rmul__(self, other):
+    def __rmul__(self, other: ExpressionOrValue) -> 'Mul':
         return Mul(other, self)
 
-    def __div__(self, other):
+    def __div__(self, other: ExpressionOrValue) -> 'Div':
         return Div(self, other)
 
     __truediv__ = __div__
 
-    def __rdiv__(self, other):
+    def __rdiv__(self, other: ExpressionOrValue) -> 'Div':
         return Div(other, self)
 
     __rtruediv__ = __rdiv__
 
-    def __pow__(self, other):
+    def __pow__(self, other: ExpressionOrValue) -> 'Pow':
         return Pow(self, other)
 
-    def __rpow__(self, other):
+    def __rpow__(self, other: ExpressionOrValue) -> 'Pow':
         return Pow(other, self)
 
-    def __neg__(self):
+    def __neg__(self) -> 'Mul':
         return Mul(-1, self)
 
-    def _substitute(self, d):
+    def _substitute(self, d: Any) -> 'ExpressionOrValue':
         return self
 
 
-def substitute(expr, d):
+ParameterSubstitutionsDict = Dict['Parameter', ExpressionValue]
+
+
+def substitute(expr: ExpressionOrValue, d: ParameterSubstitutionsDict) -> ExpressionOrValue:
     """
     Using a dictionary of substitutions ``d`` try and explicitly evaluate as much of ``expr`` as
     possible.
@@ -280,13 +317,13 @@ def substitute(expr, d):
     :return: A partially simplified Expression or a number.
     :rtype: Union[Expression,int,float]
     """
-    try:
+    if isinstance(expr, Expression):
         return expr._substitute(d)
-    except AttributeError:
-        return expr
+    return expr
 
 
-def substitute_array(a, d):
+def substitute_array(a: Union[List[Expression], np.array],
+                     d: ParameterSubstitutionsDict) -> np.array:
     """
     Apply ``substitute`` to all elements of an array ``a`` and return the resulting array.
 
@@ -304,22 +341,22 @@ class Parameter(QuilAtom, Expression):
     Parameters in Quil are represented as a label like '%x' for the parameter named 'x'.
     """
 
-    def __init__(self, name):
+    def __init__(self, name: str) -> None:
         self.name = name
 
-    def out(self):
+    def out(self) -> str:
         return '%' + self.name
 
-    def _substitute(self, d):
+    def _substitute(self, d: ParameterSubstitutionsDict) -> Union['Parameter', ExpressionValue]:
         return d.get(self, self)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return '%' + self.name
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.name)
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return isinstance(other, Parameter) and other.name == self.name
 
 
@@ -327,69 +364,71 @@ class Function(Expression):
     """
     Supported functions in Quil are sin, cos, sqrt, exp, and cis
     """
-    def __init__(self, name, expression, fn):
+    def __init__(self, name: str, expression: ExpressionOrValue, fn: Callable) -> None:
         self.name = name
         self.expression = expression
         self.fn = fn
 
-    def _substitute(self, d):
+    def _substitute(self, d: ParameterSubstitutionsDict) -> Union['Function', ExpressionValue]:
         sop = substitute(self.expression, d)
         if isinstance(sop, Expression):
             return Function(self.name, sop, self.fn)
         return self.fn(sop)
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return (isinstance(other, Function)
                 and self.name == other.name
                 and self.expression == other.expression)
 
-    def __neq__(self, other):
+    def __neq__(self, other: 'Function'):
         return not self.__eq__(other)
 
 
-def quil_sin(expression):
+def quil_sin(expression: ExpressionOrValue) -> Function:
     return Function('SIN', expression, np.sin)
 
 
-def quil_cos(expression):
+def quil_cos(expression: ExpressionOrValue) -> Function:
     return Function('COS', expression, np.cos)
 
 
-def quil_sqrt(expression):
+def quil_sqrt(expression: ExpressionOrValue) -> Function:
     return Function('SQRT', expression, np.sqrt)
 
 
-def quil_exp(expression):
+def quil_exp(expression: ExpressionOrValue) -> Function:
     return Function('EXP', expression, np.exp)
 
 
-def quil_cis(expression):
+def quil_cis(expression: ExpressionOrValue) -> Function:
     return Function('CIS', expression, lambda x: np.exp(1j * x))
 
 
 class BinaryExp(Expression):
-    operator = None     # type: str
-    precedence = None   # type: int
-    associates = None   # type: str
+    operator: ClassVar[str]
+    precedence: ClassVar[int]
+    associates: ClassVar[str]
 
+    # TODO:(appleby) what are a and b types? Expression?
     @staticmethod
-    def fn(a, b):
+    def fn(a: ExpressionOrValue, b: ExpressionOrValue):
         raise NotImplementedError
 
-    def __init__(self, op1, op2):
+    # TODO:(appleby) what are op types? Expression?
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
         self.op1 = op1
         self.op2 = op2
 
-    def _substitute(self, d):
+    def _substitute(self, d: ParameterSubstitutionsDict) -> Union['BinaryExp', ExpressionValue]:
         sop1, sop2 = substitute(self.op1, d), substitute(self.op2, d)
         return self.fn(sop1, sop2)
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return (isinstance(other, type(self))
                 and self.op1 == other.op1
                 and self.op2 == other.op2)
 
-    def __neq__(self, other):
+    def __neq__(self, other: 'BinaryExp') -> bool:
         return not self.__eq__(other)
 
 
@@ -399,10 +438,10 @@ class Add(BinaryExp):
     associates = 'both'
 
     @staticmethod
-    def fn(a, b):
+    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Add', ExpressionValue]:
         return a + b
 
-    def __init__(self, op1, op2):
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
         super(Add, self).__init__(op1, op2)
 
 
@@ -412,10 +451,10 @@ class Sub(BinaryExp):
     associates = 'left'
 
     @staticmethod
-    def fn(a, b):
+    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Sub', ExpressionValue]:
         return a - b
 
-    def __init__(self, op1, op2):
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
         super(Sub, self).__init__(op1, op2)
 
 
@@ -425,10 +464,10 @@ class Mul(BinaryExp):
     associates = 'both'
 
     @staticmethod
-    def fn(a, b):
+    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Mul', ExpressionValue]:
         return a * b
 
-    def __init__(self, op1, op2):
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
         super(Mul, self).__init__(op1, op2)
 
 
@@ -438,10 +477,10 @@ class Div(BinaryExp):
     associates = 'left'
 
     @staticmethod
-    def fn(a, b):
+    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Div', ExpressionValue]:
         return a / b
 
-    def __init__(self, op1, op2):
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
         super(Div, self).__init__(op1, op2)
 
 
@@ -451,14 +490,14 @@ class Pow(BinaryExp):
     associates = 'right'
 
     @staticmethod
-    def fn(a, b):
+    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Pow', ExpressionValue]:
         return a ** b
 
-    def __init__(self, op1, op2):
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
         super(Pow, self).__init__(op1, op2)
 
 
-def _expression_to_string(expression):
+def _expression_to_string(expression: ExpressionOrValue) -> str:
     """
     Recursively converts an expression to a string taking into account precedence and associativity for placing
     parenthesis
@@ -497,7 +536,7 @@ def _expression_to_string(expression):
         return format_parameter(expression)
 
 
-def _contained_parameters(expression):
+def _contained_parameters(expression: ExpressionOrValue) -> Set[Parameter]:
     """
     Determine which parameters are contained in this expression.
 
@@ -515,7 +554,7 @@ def _contained_parameters(expression):
         return set()
 
 
-def _check_for_pi(element):
+def _check_for_pi(element: float) -> str:
     """
     Check to see if there exists a rational number r = p/q
     in reduced form for which the difference between element/np.pi
@@ -554,37 +593,37 @@ class MemoryReference(QuilAtom, Expression):
         the declared variable is of length >1 or 1, resp.
     """
 
-    def __init__(self, name, offset=0, declared_size=None):
+    def __init__(self, name: str, offset: int = 0, declared_size: Optional[int] = None) -> None:
         if not isinstance(offset, int) or offset < 0:
             raise TypeError("MemoryReference offset must be a non-negative int")
         self.name = name
         self.offset = offset
         self.declared_size = declared_size
 
-    def out(self):
+    def out(self) -> str:
         if self.declared_size is not None and self.declared_size == 1 and self.offset == 0:
             return "{}".format(self.name)
         else:
             return "{}[{}]".format(self.name, self.offset)
 
-    def __str__(self):
+    def __str__(self) -> str:
         if self.declared_size is not None and self.declared_size == 1 and self.offset == 0:
             return "{}".format(self.name)
         else:
             return "{}[{}]".format(self.name, self.offset)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<MRef {}[{}]>".format(self.name, self.offset)
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return (isinstance(other, MemoryReference)
                 and other.name == self.name
                 and other.offset == self.offset)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash((self.name, self.offset))
 
-    def __getitem__(self, offset):
+    def __getitem__(self, offset: int) -> 'MemoryReference':
         if self.offset != 0:
             raise ValueError("Please only index off of the base MemoryReference (offset = 0)")
 
@@ -608,38 +647,8 @@ class Addr(MemoryReference):
     :param int value: The classical address.
     """
 
-    def __init__(self, value):
+    def __init__(self, value: int) -> None:
         warn("Addr objects have been deprecated. Defaulting to memory region \"ro\". Use MemoryReference instead.")
         if not isinstance(value, int) or value < 0:
             raise TypeError("Addr value must be a non-negative int")
         super(Addr, self).__init__("ro", offset=value, declared_size=None)
-
-
-# Like the Tuple, the List must be length 2, where the first item is a string and the second is an
-# int.
-MemoryReferenceDesignator = Union[MemoryReference, str, Tuple[str, int], List[Union[str, int]]]
-
-
-def unpack_classical_reg(c: MemoryReferenceDesignator) -> MemoryReference:
-    """
-    Get the address for a classical register.
-
-    :param c: A list of length 2, a pair, a string (to be interpreted as name[0]), or a MemoryReference.
-    :return: The address as a MemoryReference.
-    """
-    if isinstance(c, list) or isinstance(c, tuple):
-        if len(c) > 2 or len(c) == 0:
-            raise ValueError("if c is a list/tuple, it should be of length <= 2")
-        if len(c) == 1:
-            c = (c[0], 0)
-        if not isinstance(c[0], str):
-            raise ValueError("if c is a list/tuple, its first member should be a string")
-        if not isinstance(c[1], int):
-            raise ValueError("if c is a list/tuple, its second member should be an int")
-        return MemoryReference(c[0], c[1])
-    if isinstance(c, MemoryReference):
-        return c
-    elif isinstance(c, str):
-        return MemoryReference(c, 0)
-    else:
-        raise TypeError("c should be a list of length 2, a pair, a string, or a MemoryReference")

From 672903815a6570e330ed836851485801d3d6de64 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Mon, 16 Sep 2019 08:50:58 -0700
Subject: [PATCH 03/25] Fix flake8 issues

---
 pyquil/gates.py | 45 +++++++++++++++++++++++----------------------
 1 file changed, 23 insertions(+), 22 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index 0a55dc3e7..60f6f1534 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -553,8 +553,8 @@ def NOT(classical_reg: MemoryReferenceDesignator) -> ClassicalNot:
     return ClassicalNot(unpack_classical_reg(classical_reg))
 
 
-def AND(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceOrImmediateValue) \
-    -> ClassicalAnd:
+def AND(classical_reg1: MemoryReferenceDesignator,
+        classical_reg2: MemoryReferenceOrImmediateValue) -> ClassicalAnd:
     """
     Produce an AND instruction.
 
@@ -568,8 +568,8 @@ def AND(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferen
     return ClassicalAnd(left, right)
 
 
-def OR(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceDesignator) \
-    -> ClassicalInclusiveOr:
+def OR(classical_reg1: MemoryReferenceDesignator,
+       classical_reg2: MemoryReferenceDesignator) -> ClassicalInclusiveOr:
     """
     Produce an OR instruction.
 
@@ -583,8 +583,8 @@ def OR(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenc
     return IOR(classical_reg2, classical_reg1)
 
 
-def IOR(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceOrImmediateValue) \
-    -> ClassicalInclusiveOr:
+def IOR(classical_reg1: MemoryReferenceDesignator,
+        classical_reg2: MemoryReferenceOrImmediateValue) -> ClassicalInclusiveOr:
     """
     Produce an inclusive OR instruction.
 
@@ -596,8 +596,8 @@ def IOR(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferen
     return ClassicalInclusiveOr(left, right)
 
 
-def XOR(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceOrImmediateValue) \
-    -> ClassicalExclusiveOr:
+def XOR(classical_reg1: MemoryReferenceDesignator,
+        classical_reg2: MemoryReferenceOrImmediateValue) -> ClassicalExclusiveOr:
     """
     Produce an exclusive OR instruction.
 
@@ -609,8 +609,8 @@ def XOR(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferen
     return ClassicalExclusiveOr(left, right)
 
 
-def MOVE(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceOrImmediateValue) \
-    -> ClassicalMove:
+def MOVE(classical_reg1: MemoryReferenceDesignator,
+         classical_reg2: MemoryReferenceOrImmediateValue) -> ClassicalMove:
     """
     Produce a MOVE instruction.
 
@@ -622,8 +622,8 @@ def MOVE(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryRefere
     return ClassicalMove(left, right)
 
 
-def EXCHANGE(classical_reg1: MemoryReferenceDesignator, classical_reg2: MemoryReferenceDesignator) \
-    -> ClassicalExchange:
+def EXCHANGE(classical_reg1: MemoryReferenceDesignator,
+             classical_reg2: MemoryReferenceDesignator) -> ClassicalExchange:
     """
     Produce an EXCHANGE instruction.
 
@@ -653,8 +653,9 @@ def LOAD(target_reg: MemoryReferenceDesignator,
 # TODO:(appleby) Docstring wrong here? ClassicalStore's __init__ will throw an exception if either
 # of the last two args are not MemoryReferences. Perhaps the comment should say that offset_reg can
 # be either MemoryReference or constant (i.e. MemoryReferenceDesignator)?
-def STORE(region_name: str, offset_reg: MemoryReferenceDesignator, source: MemoryReference) \
-    -> ClassicalStore:
+def STORE(region_name: str,
+          offset_reg: MemoryReferenceDesignator,
+          source: MemoryReference) -> ClassicalStore:
     """
     Produce a STORE instruction.
 
@@ -681,8 +682,8 @@ def CONVERT(classical_reg1: MemoryReference, classical_reg2: MemoryReference) ->
                             unpack_classical_reg(classical_reg2))
 
 
-def ADD(classical_reg: MemoryReferenceDesignator, right: MemoryReferenceOrImmediateValue) \
-    -> ClassicalAdd:
+def ADD(classical_reg: MemoryReferenceDesignator,
+        right: MemoryReferenceOrImmediateValue) -> ClassicalAdd:
     """
     Produce an ADD instruction.
 
@@ -694,8 +695,8 @@ def ADD(classical_reg: MemoryReferenceDesignator, right: MemoryReferenceOrImmedi
     return ClassicalAdd(left, right)
 
 
-def SUB(classical_reg: MemoryReferenceDesignator, right: MemoryReferenceOrImmediateValue) \
-    -> ClassicalSub:
+def SUB(classical_reg: MemoryReferenceDesignator,
+        right: MemoryReferenceOrImmediateValue) -> ClassicalSub:
     """
     Produce a SUB instruction.
 
@@ -707,8 +708,8 @@ def SUB(classical_reg: MemoryReferenceDesignator, right: MemoryReferenceOrImmedi
     return ClassicalSub(left, right)
 
 
-def MUL(classical_reg: MemoryReferenceDesignator, right: MemoryReferenceOrImmediateValue) \
-    -> ClassicalMul:
+def MUL(classical_reg: MemoryReferenceDesignator,
+        right: MemoryReferenceOrImmediateValue) -> ClassicalMul:
     """
     Produce a MUL instruction.
 
@@ -720,8 +721,8 @@ def MUL(classical_reg: MemoryReferenceDesignator, right: MemoryReferenceOrImmedi
     return ClassicalMul(left, right)
 
 
-def DIV(classical_reg: MemoryReferenceDesignator, right: MemoryReferenceOrImmediateValue) \
-    -> ClassicalDiv:
+def DIV(classical_reg: MemoryReferenceDesignator,
+        right: MemoryReferenceOrImmediateValue) -> ClassicalDiv:
     """
     Produce an DIV instruction.
 

From 1aa3649c7946a3bc8d6aee72f181989f89c5b69c Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Mon, 16 Sep 2019 17:05:36 -0700
Subject: [PATCH 04/25] Resolve remaining TODO comments in source

- Replace GateParameter with ParameterDesignator everywhere

- Allow immediate floats as third arg in prepare_ternary_operands

- Allow immediate values as source arg for STORE and ClassicalStore

Fixes #815
---
 pyquil/gates.py    | 50 ++++++++++++++++++++--------------------------
 pyquil/quilatom.py |  2 --
 2 files changed, 22 insertions(+), 30 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index 60f6f1534..4dffc5dfe 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -16,8 +16,9 @@
 from warnings import warn
 from typing import Any, Callable, Dict, Optional, Tuple, Union
 
-from pyquil.quilatom import (Addr, MemoryReference, MemoryReferenceDesignator, Parameter, Qubit,
-                             QubitDesignator, QubitPlaceholder, unpack_classical_reg, unpack_qubit)
+from pyquil.quilatom import (Addr, MemoryReference, MemoryReferenceDesignator, Parameter,
+                             ParameterDesignator, Qubit, QubitDesignator, QubitPlaceholder,
+                             unpack_classical_reg, unpack_qubit)
 from pyquil.quilbase import (AbstractInstruction, Gate, Halt, Reset, ResetQubit, Measurement, Nop,
                              Wait,
                              ClassicalNeg, ClassicalNot,
@@ -30,9 +31,6 @@
 
 
 MemoryReferenceOrImmediateValue = Union[MemoryReferenceDesignator, int, float]
-MemoryReferenceOrImmediateInt = Union[MemoryReferenceDesignator, int]
-# TODO:(appleby) Should this type just be quilatom.ParameterDesignator?
-GateParameter = Union[Parameter, MemoryReference, int, float, complex]
 
 
 def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
@@ -53,9 +51,8 @@ def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
 
 def prepare_ternary_operands(classical_reg1: MemoryReferenceDesignator,
                              classical_reg2: MemoryReferenceDesignator,
-                             # TODO:(appleby) why doesn't prepare_ternary_operands allow floats for classical_reg3
-                             classical_reg3: MemoryReferenceOrImmediateInt) \
-                             -> Tuple[MemoryReference, MemoryReference, MemoryReferenceOrImmediateInt]:
+                             classical_reg3: MemoryReferenceOrImmediateValue) \
+                             -> Tuple[MemoryReference, MemoryReference, MemoryReferenceOrImmediateValue]:
     """
     Helper function for typechecking / type-coercing arguments to constructors for ternary classical operators.
 
@@ -177,7 +174,7 @@ def T(qubit: QubitDesignator) -> Gate:
     return Gate(name="T", params=[], qubits=[unpack_qubit(qubit)])
 
 
-def RX(angle: GateParameter, qubit: QubitDesignator) -> Gate:
+def RX(angle: ParameterDesignator, qubit: QubitDesignator) -> Gate:
     """Produces the RX gate::
 
         RX(phi) = [[cos(phi / 2), -1j * sin(phi / 2)],
@@ -192,7 +189,7 @@ def RX(angle: GateParameter, qubit: QubitDesignator) -> Gate:
     return Gate(name="RX", params=[angle], qubits=[unpack_qubit(qubit)])
 
 
-def RY(angle: GateParameter, qubit: QubitDesignator) -> Gate:
+def RY(angle: ParameterDesignator, qubit: QubitDesignator) -> Gate:
     """Produces the RY gate::
 
         RY(phi) = [[cos(phi / 2), -sin(phi / 2)],
@@ -207,7 +204,7 @@ def RY(angle: GateParameter, qubit: QubitDesignator) -> Gate:
     return Gate(name="RY", params=[angle], qubits=[unpack_qubit(qubit)])
 
 
-def RZ(angle: GateParameter, qubit: QubitDesignator) -> Gate:
+def RZ(angle: ParameterDesignator, qubit: QubitDesignator) -> Gate:
     """Produces the RZ gate::
 
         RZ(phi) = [[cos(phi / 2) - 1j * sin(phi / 2), 0]
@@ -222,7 +219,7 @@ def RZ(angle: GateParameter, qubit: QubitDesignator) -> Gate:
     return Gate(name="RZ", params=[angle], qubits=[unpack_qubit(qubit)])
 
 
-def PHASE(angle: GateParameter, qubit: QubitDesignator) -> Gate:
+def PHASE(angle: ParameterDesignator, qubit: QubitDesignator) -> Gate:
     """Produces the PHASE gate::
 
         PHASE(phi) = [[1, 0],
@@ -299,7 +296,7 @@ def CCNOT(control1: QubitDesignator, control2: QubitDesignator, target: QubitDes
     return Gate(name="CCNOT", params=[], qubits=qubits)
 
 
-def CPHASE00(angle: GateParameter, control: QubitDesignator, target: QubitDesignator) -> Gate:
+def CPHASE00(angle: ParameterDesignator, control: QubitDesignator, target: QubitDesignator) -> Gate:
     """Produces a controlled-phase gate that phases the ``|00>`` state::
 
         CPHASE00(phi) = diag([exp(1j * phi), 1, 1, 1])
@@ -316,7 +313,7 @@ def CPHASE00(angle: GateParameter, control: QubitDesignator, target: QubitDesign
     return Gate(name="CPHASE00", params=[angle], qubits=qubits)
 
 
-def CPHASE01(angle: GateParameter, control: QubitDesignator, target: QubitDesignator) -> Gate:
+def CPHASE01(angle: ParameterDesignator, control: QubitDesignator, target: QubitDesignator) -> Gate:
     """Produces a controlled-phase gate that phases the ``|01>`` state::
 
         CPHASE01(phi) = diag([1.0, exp(1j * phi), 1.0, 1.0])
@@ -334,7 +331,7 @@ def CPHASE01(angle: GateParameter, control: QubitDesignator, target: QubitDesign
     return Gate(name="CPHASE01", params=[angle], qubits=qubits)
 
 
-def CPHASE10(angle: GateParameter, control: QubitDesignator, target: QubitDesignator) -> Gate:
+def CPHASE10(angle: ParameterDesignator, control: QubitDesignator, target: QubitDesignator) -> Gate:
     """Produces a controlled-phase gate that phases the ``|10>`` state::
 
         CPHASE10(phi) = diag([1, 1, exp(1j * phi), 1])
@@ -352,7 +349,7 @@ def CPHASE10(angle: GateParameter, control: QubitDesignator, target: QubitDesign
     return Gate(name="CPHASE10", params=[angle], qubits=qubits)
 
 
-def CPHASE(angle: GateParameter, control: QubitDesignator, target: QubitDesignator) -> Gate:
+def CPHASE(angle: ParameterDesignator, control: QubitDesignator, target: QubitDesignator) -> Gate:
     """Produces a controlled-phase instruction::
 
         CPHASE(phi) = diag([1, 1, 1, exp(1j * phi)])
@@ -428,7 +425,7 @@ def ISWAP(q1: QubitDesignator, q2: QubitDesignator) -> Gate:
     return Gate(name="ISWAP", params=[], qubits=[unpack_qubit(q) for q in (q1, q2)])
 
 
-def PSWAP(angle: GateParameter, q1: QubitDesignator, q2: QubitDesignator) -> Gate:
+def PSWAP(angle: ParameterDesignator, q1: QubitDesignator, q2: QubitDesignator) -> Gate:
     """Produces a parameterized SWAP gate::
 
         PSWAP(phi) = [[1, 0,             0,             0],
@@ -650,12 +647,9 @@ def LOAD(target_reg: MemoryReferenceDesignator,
     return ClassicalLoad(unpack_classical_reg(target_reg), region_name, unpack_classical_reg(offset_reg))
 
 
-# TODO:(appleby) Docstring wrong here? ClassicalStore's __init__ will throw an exception if either
-# of the last two args are not MemoryReferences. Perhaps the comment should say that offset_reg can
-# be either MemoryReference or constant (i.e. MemoryReferenceDesignator)?
 def STORE(region_name: str,
           offset_reg: MemoryReferenceDesignator,
-          source: MemoryReference) -> ClassicalStore:
+          source: MemoryReferenceOrImmediateValue) -> ClassicalStore:
     """
     Produce a STORE instruction.
 
@@ -669,8 +663,8 @@ def STORE(region_name: str,
     return ClassicalStore(region_name, unpack_classical_reg(offset_reg), source)
 
 
-# TODO:(appleby) should this take 2 MemoryReferenceDesignators and call unpack_classical_reg on them?
-def CONVERT(classical_reg1: MemoryReference, classical_reg2: MemoryReference) -> ClassicalConvert:
+def CONVERT(classical_reg1: MemoryReferenceDesignator,
+            classical_reg2: MemoryReferenceDesignator) -> ClassicalConvert:
     """
     Produce a CONVERT instruction.
 
@@ -736,7 +730,7 @@ def DIV(classical_reg: MemoryReferenceDesignator,
 
 def EQ(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MemoryReferenceOrImmediateInt) -> ClassicalEqual:
+       classical_reg3: MemoryReferenceOrImmediateValue) -> ClassicalEqual:
     """
     Produce an EQ instruction.
 
@@ -754,7 +748,7 @@ def EQ(classical_reg1: MemoryReferenceDesignator,
 
 def LT(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MemoryReferenceOrImmediateInt) -> ClassicalLessThan:
+       classical_reg3: MemoryReferenceOrImmediateValue) -> ClassicalLessThan:
     """
     Produce an LT instruction.
 
@@ -771,7 +765,7 @@ def LT(classical_reg1: MemoryReferenceDesignator,
 
 def LE(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MemoryReferenceOrImmediateInt) -> ClassicalLessEqual:
+       classical_reg3: MemoryReferenceOrImmediateValue) -> ClassicalLessEqual:
     """
     Produce an LE instruction.
 
@@ -788,7 +782,7 @@ def LE(classical_reg1: MemoryReferenceDesignator,
 
 def GT(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MemoryReferenceOrImmediateInt) -> ClassicalGreaterThan:
+       classical_reg3: MemoryReferenceOrImmediateValue) -> ClassicalGreaterThan:
     """
     Produce an GT instruction.
 
@@ -805,7 +799,7 @@ def GT(classical_reg1: MemoryReferenceDesignator,
 
 def GE(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MemoryReferenceOrImmediateInt) -> ClassicalGreaterEqual:
+       classical_reg3: MemoryReferenceOrImmediateValue) -> ClassicalGreaterEqual:
     """
     Produce an GE instruction.
 
diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index f46635db8..c49dea64c 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -409,12 +409,10 @@ class BinaryExp(Expression):
     precedence: ClassVar[int]
     associates: ClassVar[str]
 
-    # TODO:(appleby) what are a and b types? Expression?
     @staticmethod
     def fn(a: ExpressionOrValue, b: ExpressionOrValue):
         raise NotImplementedError
 
-    # TODO:(appleby) what are op types? Expression?
     def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
         self.op1 = op1
         self.op2 = op2

From 0570f4e5581d40e7a25de4837fc3fb38763e3422 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Mon, 16 Sep 2019 17:32:44 -0700
Subject: [PATCH 05/25] Update the changelog for gh-999

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 52a0b7a27..7f080c5c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -78,6 +78,7 @@ Changelog
     the `--runslow` option is specified for `pytest` (@kilimanjaro, gh-1001).
 -   `PauliSum` objects can now be constructed from strings via `from_compact_str()`
     and `PauliTerm.from_compact_str()` supports multi-qubit strings (@jlbosse, gh-984).
+-   Type hints have been added to `pyquil.gates` and `pyquil.quilatom` modules (@appleby gh-999).
 
 ### Bugfixes
 

From abf326e732d4b05e1b5f516e14581129c2a0749e Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Mon, 16 Sep 2019 18:03:04 -0700
Subject: [PATCH 06/25] Appease sphinx by importing quilatom.Expression in
 gates.py

Import quilatom.Expression in gates.py. Even though it isn't
referenced directly, it is indirectly used by
quilatom.ParameterDesignator, which causes sphinx to choke when
generating the docs.
---
 pyquil/gates.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index 4dffc5dfe..2c02b4a00 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -16,9 +16,9 @@
 from warnings import warn
 from typing import Any, Callable, Dict, Optional, Tuple, Union
 
-from pyquil.quilatom import (Addr, MemoryReference, MemoryReferenceDesignator, Parameter,
-                             ParameterDesignator, Qubit, QubitDesignator, QubitPlaceholder,
-                             unpack_classical_reg, unpack_qubit)
+from pyquil.quilatom import (Addr, Expression, MemoryReference, MemoryReferenceDesignator,
+                             Parameter, ParameterDesignator, Qubit, QubitDesignator,
+                             QubitPlaceholder, unpack_classical_reg, unpack_qubit)
 from pyquil.quilbase import (AbstractInstruction, Gate, Halt, Reset, ResetQubit, Measurement, Nop,
                              Wait,
                              ClassicalNeg, ClassicalNot,

From 698986068a0682d1f5aa5837eb47ba0b6b305789 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Tue, 17 Sep 2019 10:58:24 -0700
Subject: [PATCH 07/25] Fix the return type for
 operator_estimation._stats_from_measurements

---
 pyquil/operator_estimation.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyquil/operator_estimation.py b/pyquil/operator_estimation.py
index 935a51951..52c26c100 100644
--- a/pyquil/operator_estimation.py
+++ b/pyquil/operator_estimation.py
@@ -550,7 +550,7 @@ def _ops_bool_to_prog(ops_bool: Tuple[bool], qubits: List[int]) -> Program:
 
 def _stats_from_measurements(bs_results: np.ndarray, qubit_index_map: Dict,
                              setting: ExperimentSetting, n_shots: int,
-                             coeff: float = 1.0) -> Tuple[float]:
+                             coeff: float = 1.0) -> Tuple[float, float]:
     """
     :param bs_results: results from running `qc.run`
     :param qubit_index_map: dict mapping qubit to classical register index

From 224e59016b22916736cdd93a9166183377934a9c Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Tue, 17 Sep 2019 10:59:16 -0700
Subject: [PATCH 08/25] Silence mypy complaints about from pyquil.gates import
 *

---
 pyquil/tests/test_gates.py                            | 3 ++-
 pyquil/tests/test_reference_wavefunction_simulator.py | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/pyquil/tests/test_gates.py b/pyquil/tests/test_gates.py
index db8b2012f..ea44258e3 100644
--- a/pyquil/tests/test_gates.py
+++ b/pyquil/tests/test_gates.py
@@ -1,5 +1,6 @@
 import pytest
-from pyquil.gates import *
+from pyquil.gates import (CNOT, CPHASE, CPHASE00, CPHASE01, CPHASE10, CZ, H, I, ISWAP, PHASE, PSWAP,
+                          RX, RY, RZ, S, SWAP, T, X, Y, Z)
 from pyquil.quilbase import _strip_modifiers
 
 
diff --git a/pyquil/tests/test_reference_wavefunction_simulator.py b/pyquil/tests/test_reference_wavefunction_simulator.py
index 0269afa47..8fba6a683 100644
--- a/pyquil/tests/test_reference_wavefunction_simulator.py
+++ b/pyquil/tests/test_reference_wavefunction_simulator.py
@@ -8,7 +8,8 @@
 import pytest
 
 from pyquil.api import WavefunctionSimulator
-from pyquil.gates import *
+from pyquil.gates import (CNOT, CPHASE, H, HALT, I, MEASURE, MOVE, PHASE, RESET, RX, RY, RZ, SWAP,
+                          X, QUANTUM_GATES)
 from pyquil.paulis import PauliTerm, exponentiate, sZ, sX, sI, sY
 from pyquil.pyqvm import PyQVM
 from pyquil.quil import Program

From 25f8088bdf4e011fff5f9c5d5d9e7d8b349072fd Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Tue, 17 Sep 2019 11:02:23 -0700
Subject: [PATCH 09/25] Fix return type of
 ForestConnection._qvm_get_version_info

---
 pyquil/api/_base_connection.py | 2 +-
 pyquil/api/_qvm.py             | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/pyquil/api/_base_connection.py b/pyquil/api/_base_connection.py
index 5596620bb..36beb9f78 100644
--- a/pyquil/api/_base_connection.py
+++ b/pyquil/api/_base_connection.py
@@ -367,7 +367,7 @@ def _qvm_run(self, quil_program, classical_addresses, trials,
         return ram
 
     @_record_call
-    def _qvm_get_version_info(self) -> dict:
+    def _qvm_get_version_info(self) -> str:
         """
         Return version information for the QVM.
 
diff --git a/pyquil/api/_qvm.py b/pyquil/api/_qvm.py
index ec6012b80..a46e0ac0f 100644
--- a/pyquil/api/_qvm.py
+++ b/pyquil/api/_qvm.py
@@ -140,7 +140,7 @@ def get_version_info(self):
         """
         Return version information for the QVM.
 
-        :return: Dictionary with version information
+        :return: String with version information
         """
         return self._connection._qvm_get_version_info()
 
@@ -448,7 +448,7 @@ def get_version_info(self):
         """
         Return version information for the QVM.
 
-        :return: Dictionary with version information
+        :return: String with version information
         """
         return self.connection._qvm_get_version_info()
 

From e60338f68e05b195e5e52af0a60d70306a0c3363 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Tue, 17 Sep 2019 13:15:52 -0700
Subject: [PATCH 10/25] Satisfy mypy --strict about pyquil.quilatom type hints

---
 pyquil/quilatom.py | 30 ++++++++++++++++------------
 pyquil/quilbase.py | 49 +++++++++++++++++++++++++---------------------
 2 files changed, 44 insertions(+), 35 deletions(-)

diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index c49dea64c..0d6ae3246 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -24,19 +24,19 @@ class QuilAtom(object):
     Abstract class for atomic elements of Quil.
     """
 
-    def out(self):
+    def out(self) -> str:
         raise NotImplementedError()
 
-    def __str__(self):
+    def __str__(self) -> str:
         raise NotImplementedError()
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         raise NotImplementedError()
 
     def __ne__(self, other: object) -> bool:
         return not self.__eq__(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         raise NotImplementedError()
 
 
@@ -69,7 +69,7 @@ def __eq__(self, other: object) -> bool:
 
 
 class QubitPlaceholder(QuilAtom):
-    def out(self):
+    def out(self) -> str:
         raise RuntimeError("Qubit {} has not been assigned an index".format(self))
 
     def __str__(self) -> str:
@@ -124,8 +124,11 @@ def unpack_qubit(qubit: QubitDesignator) -> Union[Qubit, QubitPlaceholder]:
         raise TypeError("qubit should be an int or Qubit instance")
 
 
-# Like the Tuple, the List must be length 2, where the first item is a string and the second an int.
-MemoryReferenceDesignator = Union['MemoryReference', Tuple[str, int], List, str]
+# Like the Tuple, the List must be length 2, where the first item is a string and the second an
+# int. However, specifying Union[str, int] as the generic type argument to List doesn't sufficiently
+# constrain the types, and mypy gets confused in unpack_classical_reg, below. Hence, just specify
+# List here and add a "# type: ignore" comment to silence mypy --strict.
+MemoryReferenceDesignator = Union['MemoryReference', Tuple[str, int], List, str]  # type: ignore
 
 
 def unpack_classical_reg(c: MemoryReferenceDesignator) -> 'MemoryReference':
@@ -183,7 +186,7 @@ class LabelPlaceholder(QuilAtom):
     def __init__(self, prefix: str = "L") -> None:
         self.prefix = prefix
 
-    def out(self):
+    def out(self) -> str:
         raise RuntimeError("Label has not been assigned a name")
 
     def __str__(self) -> str:
@@ -244,7 +247,7 @@ def format_parameter(element: ParameterDesignator) -> str:
     assert False, "Invalid parameter: %r" % element
 
 
-ExpressionValue = Union[int, float]
+ExpressionValue = Union[int, float, complex]
 ExpressionOrValue = Union['Expression', ExpressionValue]
 
 
@@ -364,7 +367,8 @@ class Function(Expression):
     """
     Supported functions in Quil are sin, cos, sqrt, exp, and cis
     """
-    def __init__(self, name: str, expression: ExpressionOrValue, fn: Callable) -> None:
+    def __init__(self, name: str, expression: ExpressionOrValue,
+                 fn: Callable[[ExpressionValue], ExpressionValue]) -> None:
         self.name = name
         self.expression = expression
         self.fn = fn
@@ -380,7 +384,7 @@ def __eq__(self, other: object) -> bool:
                 and self.name == other.name
                 and self.expression == other.expression)
 
-    def __neq__(self, other: 'Function'):
+    def __neq__(self, other: 'Function') -> bool:
         return not self.__eq__(other)
 
 
@@ -401,7 +405,7 @@ def quil_exp(expression: ExpressionOrValue) -> Function:
 
 
 def quil_cis(expression: ExpressionOrValue) -> Function:
-    return Function('CIS', expression, lambda x: np.exp(1j * x))
+    return Function('CIS', expression, lambda x: np.exp(1j * x))  # type: ignore
 
 
 class BinaryExp(Expression):
@@ -410,7 +414,7 @@ class BinaryExp(Expression):
     associates: ClassVar[str]
 
     @staticmethod
-    def fn(a: ExpressionOrValue, b: ExpressionOrValue):
+    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['BinaryExp', ExpressionValue]:
         raise NotImplementedError
 
     def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
diff --git a/pyquil/quilbase.py b/pyquil/quilbase.py
index 79b789977..af3c38b30 100644
--- a/pyquil/quilbase.py
+++ b/pyquil/quilbase.py
@@ -88,8 +88,13 @@ class Gate(AbstractInstruction):
     This is the pyQuil object for a quantum gate instruction.
     """
 
+<<<<<<< HEAD
     def __init__(self, name, params, qubits):
         if not isinstance(name, str):
+=======
+    def __init__(self, name, params, qubits) -> None:
+        if not isinstance(name, string_types):
+>>>>>>> Satisfy mypy --strict about pyquil.quilatom type hints
             raise TypeError("Gate name must be a string")
 
         if name in RESERVED_WORDS:
@@ -220,7 +225,7 @@ class Measurement(AbstractInstruction):
     This is the pyQuil object for a Quil measurement instruction.
     """
 
-    def __init__(self, qubit, classical_reg):
+    def __init__(self, qubit, classical_reg) -> None:
         if not isinstance(qubit, (Qubit, QubitPlaceholder)):
             raise TypeError("qubit should be a Qubit")
         if classical_reg and not isinstance(classical_reg, MemoryReference):
@@ -250,7 +255,7 @@ class ResetQubit(AbstractInstruction):
     This is the pyQuil object for a Quil targeted reset instruction.
     """
 
-    def __init__(self, qubit):
+    def __init__(self, qubit) -> None:
         if not isinstance(qubit, (Qubit, QubitPlaceholder)):
             raise TypeError("qubit should be a Qubit")
         self.qubit = qubit
@@ -274,7 +279,7 @@ class DefGate(AbstractInstruction):
     :param list parameters: list of parameters that are used in this gate
     """
 
-    def __init__(self, name, matrix, parameters=None):
+    def __init__(self, name, matrix, parameters=None) -> None:
         if not isinstance(name, str):
             raise TypeError("Gate name must be a string")
 
@@ -369,7 +374,7 @@ def num_args(self):
 
 
 class DefPermutationGate(DefGate):
-    def __init__(self, name, permutation):
+    def __init__(self, name, permutation) -> None:
         if not isinstance(name, str):
             raise TypeError("Gate name must be a string")
 
@@ -409,7 +414,7 @@ class JumpTarget(AbstractInstruction):
     Representation of a target that can be jumped to.
     """
 
-    def __init__(self, label):
+    def __init__(self, label) -> None:
         if not isinstance(label, (Label, LabelPlaceholder)):
             raise TypeError("label must be a Label")
         self.label = label
@@ -427,7 +432,7 @@ class JumpConditional(AbstractInstruction):
     """
     op = NotImplemented
 
-    def __init__(self, target, condition):
+    def __init__(self, target, condition) -> None:
         if not isinstance(target, (Label, LabelPlaceholder)):
             raise TypeError("target should be a Label")
         if not isinstance(condition, MemoryReference):
@@ -495,7 +500,7 @@ class UnaryClassicalInstruction(AbstractInstruction):
     The abstract class for unary classical instructions.
     """
 
-    def __init__(self, target):
+    def __init__(self, target) -> None:
         if not isinstance(target, MemoryReference):
             raise TypeError("target operand should be an MemoryReference")
         self.target = target
@@ -524,7 +529,7 @@ class LogicalBinaryOp(AbstractInstruction):
     """
     op = NotImplemented
 
-    def __init__(self, left, right):
+    def __init__(self, left, right) -> None:
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference) and not isinstance(right, int):
@@ -569,7 +574,7 @@ class ClassicalOr(ClassicalInclusiveOr):
     Deprecated class.
     """
 
-    def __init__(self, left, right):
+    def __init__(self, left, right) -> None:
         warn("ClassicalOr has been deprecated. Replacing with "
              "ClassicalInclusiveOr. Use ClassicalInclusiveOr instead. "
              "NOTE: The operands to ClassicalInclusiveOr are inverted from "
@@ -582,7 +587,7 @@ class ArithmeticBinaryOp(AbstractInstruction):
     The abstract class for binary arithmetic classical instructions.
     """
 
-    def __init__(self, left, right):
+    def __init__(self, left, right) -> None:
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference) and not isinstance(right, int) and not isinstance(right, float):
@@ -632,7 +637,7 @@ class ClassicalMove(AbstractInstruction):
     """
     op = "MOVE"
 
-    def __init__(self, left, right):
+    def __init__(self, left, right) -> None:
         if not isinstance(left, MemoryReference):
             raise TypeError("Left operand of MOVE should be an MemoryReference.  "
                             "Note that the order of the operands in pyQuil 2.0 has reversed from "
@@ -652,7 +657,7 @@ class ClassicalFalse(ClassicalMove):
     Deprecated class.
     """
 
-    def __init__(self, target):
+    def __init__(self, target) -> None:
         super().__init__(target, 0)
         warn("ClassicalFalse is deprecated in favor of ClassicalMove.")
 
@@ -662,7 +667,7 @@ class ClassicalTrue(ClassicalMove):
     Deprecated class.
     """
 
-    def __init__(self, target):
+    def __init__(self, target) -> None:
         super().__init__(target, 1)
         warn("ClassicalTrue is deprecated in favor of ClassicalMove.")
 
@@ -674,7 +679,7 @@ class ClassicalExchange(AbstractInstruction):
 
     op = "EXCHANGE"
 
-    def __init__(self, left, right):
+    def __init__(self, left, right) -> None:
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference):
@@ -693,7 +698,7 @@ class ClassicalConvert(AbstractInstruction):
 
     op = "CONVERT"
 
-    def __init__(self, left, right):
+    def __init__(self, left, right) -> None:
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference):
@@ -712,7 +717,7 @@ class ClassicalLoad(AbstractInstruction):
 
     op = "LOAD"
 
-    def __init__(self, target, left, right):
+    def __init__(self, target, left, right) -> None:
         if not isinstance(target, MemoryReference):
             raise TypeError("target operand should be an MemoryReference")
         if not isinstance(right, MemoryReference):
@@ -732,7 +737,7 @@ class ClassicalStore(AbstractInstruction):
 
     op = "STORE"
 
-    def __init__(self, target, left, right):
+    def __init__(self, target, left, right) -> None:
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not (isinstance(right, MemoryReference) or isinstance(right, int)
@@ -751,7 +756,7 @@ class ClassicalComparison(AbstractInstruction):
     Abstract class for ternary comparison instructions.
     """
 
-    def __init__(self, target, left, right):
+    def __init__(self, target, left, right) -> None:
         if not isinstance(target, MemoryReference):
             raise TypeError("target operand should be an MemoryReference")
         if not isinstance(left, MemoryReference):
@@ -809,7 +814,7 @@ class Jump(AbstractInstruction):
     Representation of an unconditional jump instruction (JUMP).
     """
 
-    def __init__(self, target):
+    def __init__(self, target) -> None:
         if not isinstance(target, (Label, LabelPlaceholder)):
             raise TypeError("target should be a Label")
         self.target = target
@@ -828,7 +833,7 @@ class Pragma(AbstractInstruction):
 
     """
 
-    def __init__(self, command, args=(), freeform_string=""):
+    def __init__(self, command, args=(), freeform_string="") -> None:
         if not isinstance(command, str):
             raise TypeError("Pragma's require an identifier.")
 
@@ -870,7 +875,7 @@ class Declare(AbstractInstruction):
 
     """
 
-    def __init__(self, name, memory_type, memory_size=1, shared_region=None, offsets=None):
+    def __init__(self, name, memory_type, memory_size=1, shared_region=None, offsets=None) -> None:
         self.name = name
         self.memory_type = memory_type
         self.memory_size = memory_size
@@ -907,7 +912,7 @@ class RawInstr(AbstractInstruction):
     A raw instruction represented as a string.
     """
 
-    def __init__(self, instr_str):
+    def __init__(self, instr_str) -> None:
         if not isinstance(instr_str, str):
             raise TypeError("Raw instructions require a string.")
         self.instr = instr_str

From b937c7099ffa1eaa6a666fffeeaab7cb5be7ae69 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Mon, 23 Sep 2019 15:03:55 -0500
Subject: [PATCH 11/25] Update docstrings and error messages to match updated
 type hints

Remove any explicit types from :param: and :rtype: sphinx docstrings,
and let sphinx-autodoc-typehints take care of it.
---
 pyquil/gates.py    |  3 +--
 pyquil/quilatom.py | 10 +++++-----
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index 2c02b4a00..92250984e 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -456,12 +456,11 @@ def RESET(qubit_index: Optional[QubitDesignator] = None) -> Union[Reset, ResetQu
     """
     Reset all qubits or just one specific qubit.
 
-    :param Optional[QubitDesignator] qubit_index: The qubit to reset.
+    :param qubit_index: The qubit to reset.
         This can be a qubit's index, a Qubit, or a QubitPlaceholder.
         If None, reset all qubits.
     :returns: A Reset or ResetQubit Quil AST expression corresponding to a global or targeted
         reset, respectively.
-    :rtype: Union[Reset, ResetQubit]
     """
     if qubit_index is not None:
         return ResetQubit(unpack_qubit(qubit_index))
diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index 0d6ae3246..ae1a5a38d 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -111,8 +111,8 @@ def unpack_qubit(qubit: QubitDesignator) -> Union[Qubit, QubitPlaceholder]:
     """
     Get a qubit from an object.
 
-    :param qubit: An int or Qubit.
-    :return: A Qubit instance
+    :param qubit: the qubit designator to unpack.
+    :return: A Qubit or QubitPlaceholder instance
     """
     if isinstance(qubit, int):
         return Qubit(qubit)
@@ -121,7 +121,7 @@ def unpack_qubit(qubit: QubitDesignator) -> Union[Qubit, QubitPlaceholder]:
     elif isinstance(qubit, QubitPlaceholder):
         return qubit
     else:
-        raise TypeError("qubit should be an int or Qubit instance")
+        raise TypeError("qubit should be an int or Qubit or QubitPlaceholder instance")
 
 
 # Like the Tuple, the List must be length 2, where the first item is a string and the second an
@@ -210,7 +210,7 @@ def format_parameter(element: ParameterDesignator) -> str:
     Formats a particular parameter. Essentially the same as built-in formatting except using 'i' instead of 'j' for
     the imaginary number.
 
-    :param element: {int, float, complex, Parameter, MemoryReference, Expression} Formats a parameter for Quil output.
+    :param element: The parameter to format for Quil output.
     """
     if isinstance(element, int) or isinstance(element, np.int_):
         return repr(element)
@@ -562,7 +562,7 @@ def _check_for_pi(element: float) -> str:
     in reduced form for which the difference between element/np.pi
     and r is small and q <= 8.
 
-    :param element: float
+    :param element: the number to check
     :return element: pretty print string if true, else standard representation.
     """
     frac = Fraction(element / np.pi).limit_denominator(8)

From 7edfc8aaa5f76569d9534e59529dc44bb8f608d2 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Wed, 9 Oct 2019 14:52:23 -0500
Subject: [PATCH 12/25] Add type annotations for the quilbase module

Resolves #1027
---
 pyquil/gates.py    |  74 ++++++++++-----
 pyquil/quilatom.py |  11 ++-
 pyquil/quilbase.py | 227 ++++++++++++++++++++++++---------------------
 3 files changed, 181 insertions(+), 131 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index 92250984e..eb00c0507 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -14,11 +14,12 @@
 #    limitations under the License.
 ##############################################################################
 from warnings import warn
-from typing import Any, Callable, Dict, Optional, Tuple, Union
+from typing import Any, Callable, Dict, Optional, Tuple, Union, overload
 
 from pyquil.quilatom import (Addr, Expression, MemoryReference, MemoryReferenceDesignator,
-                             Parameter, ParameterDesignator, Qubit, QubitDesignator,
-                             QubitPlaceholder, unpack_classical_reg, unpack_qubit)
+                             MRefDesignatorOrImmediateInt, MRefDesignatorOrImmediateValue,
+                             MRefOrImmediateValue, Parameter, ParameterDesignator, Qubit,
+                             QubitDesignator, QubitPlaceholder, unpack_classical_reg, unpack_qubit)
 from pyquil.quilbase import (AbstractInstruction, Gate, Halt, Reset, ResetQubit, Measurement, Nop,
                              Wait,
                              ClassicalNeg, ClassicalNot,
@@ -30,12 +31,37 @@
                              ClassicalAdd, ClassicalSub, ClassicalMul, ClassicalDiv)
 
 
-MemoryReferenceOrImmediateValue = Union[MemoryReferenceDesignator, int, float]
+# These @overloads are needed to help mypy with type inference. Note that the order of the overloads
+# is important! According to the mypy docs, overloads should proceed from most-specific ->
+# least-specific type, and should appear in the same order as the isinstance checks in the
+# implementation body.
+#
+# https://mypy.readthedocs.io/en/latest/more_types.html#function-overloading
+# https://github.com/python/mypy/issues/1693
+@overload
+def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
+                        classical_reg2: int) \
+                        -> Tuple[MemoryReference, int]:
+    ...
+
+
+@overload
+def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
+                        classical_reg2: float) \
+                        -> Tuple[MemoryReference, float]:
+    ...
+
+
+@overload
+def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
+                        classical_reg2: MemoryReferenceDesignator) \
+                        -> Tuple[MemoryReference, MemoryReference]:
+    ...
 
 
 def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
-                        classical_reg2: MemoryReferenceOrImmediateValue) \
-                        -> Tuple[MemoryReference, MemoryReferenceOrImmediateValue]:
+                        classical_reg2: MRefDesignatorOrImmediateValue) \
+                        -> Tuple[MemoryReference, MRefOrImmediateValue]:
     """
     Helper function for typechecking / type-coercing arguments to constructors for binary classical operators.
 
@@ -44,15 +70,15 @@ def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
     :return: A pair of pyQuil objects suitable for use as operands.
     """
     left = unpack_classical_reg(classical_reg1)
-    if isinstance(classical_reg2, int) or isinstance(classical_reg2, float):
+    if isinstance(classical_reg2, (float, int)):
         return left, classical_reg2
     return left, unpack_classical_reg(classical_reg2)
 
 
 def prepare_ternary_operands(classical_reg1: MemoryReferenceDesignator,
                              classical_reg2: MemoryReferenceDesignator,
-                             classical_reg3: MemoryReferenceOrImmediateValue) \
-                             -> Tuple[MemoryReference, MemoryReference, MemoryReferenceOrImmediateValue]:
+                             classical_reg3: MRefDesignatorOrImmediateValue) \
+                             -> Tuple[MemoryReference, MemoryReference, MRefOrImmediateValue]:
     """
     Helper function for typechecking / type-coercing arguments to constructors for ternary classical operators.
 
@@ -67,7 +93,7 @@ def prepare_ternary_operands(classical_reg1: MemoryReferenceDesignator,
     if isinstance(classical_reg2, int):
         raise TypeError("Left operand of comparison must be a memory address")
     classical_reg2 = unpack_classical_reg(classical_reg2)
-    if not isinstance(classical_reg3, int) and not isinstance(classical_reg3, float):
+    if not isinstance(classical_reg3, (float, int)):
         classical_reg3 = unpack_classical_reg(classical_reg3)
 
     return classical_reg1, classical_reg2, classical_reg3
@@ -550,7 +576,7 @@ def NOT(classical_reg: MemoryReferenceDesignator) -> ClassicalNot:
 
 
 def AND(classical_reg1: MemoryReferenceDesignator,
-        classical_reg2: MemoryReferenceOrImmediateValue) -> ClassicalAnd:
+        classical_reg2: MRefDesignatorOrImmediateInt) -> ClassicalAnd:
     """
     Produce an AND instruction.
 
@@ -580,7 +606,7 @@ def OR(classical_reg1: MemoryReferenceDesignator,
 
 
 def IOR(classical_reg1: MemoryReferenceDesignator,
-        classical_reg2: MemoryReferenceOrImmediateValue) -> ClassicalInclusiveOr:
+        classical_reg2: MRefDesignatorOrImmediateInt) -> ClassicalInclusiveOr:
     """
     Produce an inclusive OR instruction.
 
@@ -593,7 +619,7 @@ def IOR(classical_reg1: MemoryReferenceDesignator,
 
 
 def XOR(classical_reg1: MemoryReferenceDesignator,
-        classical_reg2: MemoryReferenceOrImmediateValue) -> ClassicalExclusiveOr:
+        classical_reg2: MRefDesignatorOrImmediateInt) -> ClassicalExclusiveOr:
     """
     Produce an exclusive OR instruction.
 
@@ -606,7 +632,7 @@ def XOR(classical_reg1: MemoryReferenceDesignator,
 
 
 def MOVE(classical_reg1: MemoryReferenceDesignator,
-         classical_reg2: MemoryReferenceOrImmediateValue) -> ClassicalMove:
+         classical_reg2: MRefDesignatorOrImmediateValue) -> ClassicalMove:
     """
     Produce a MOVE instruction.
 
@@ -648,7 +674,7 @@ def LOAD(target_reg: MemoryReferenceDesignator,
 
 def STORE(region_name: str,
           offset_reg: MemoryReferenceDesignator,
-          source: MemoryReferenceOrImmediateValue) -> ClassicalStore:
+          source: MRefDesignatorOrImmediateValue) -> ClassicalStore:
     """
     Produce a STORE instruction.
 
@@ -676,7 +702,7 @@ def CONVERT(classical_reg1: MemoryReferenceDesignator,
 
 
 def ADD(classical_reg: MemoryReferenceDesignator,
-        right: MemoryReferenceOrImmediateValue) -> ClassicalAdd:
+        right: MRefDesignatorOrImmediateValue) -> ClassicalAdd:
     """
     Produce an ADD instruction.
 
@@ -689,7 +715,7 @@ def ADD(classical_reg: MemoryReferenceDesignator,
 
 
 def SUB(classical_reg: MemoryReferenceDesignator,
-        right: MemoryReferenceOrImmediateValue) -> ClassicalSub:
+        right: MRefDesignatorOrImmediateValue) -> ClassicalSub:
     """
     Produce a SUB instruction.
 
@@ -702,7 +728,7 @@ def SUB(classical_reg: MemoryReferenceDesignator,
 
 
 def MUL(classical_reg: MemoryReferenceDesignator,
-        right: MemoryReferenceOrImmediateValue) -> ClassicalMul:
+        right: MRefDesignatorOrImmediateValue) -> ClassicalMul:
     """
     Produce a MUL instruction.
 
@@ -715,7 +741,7 @@ def MUL(classical_reg: MemoryReferenceDesignator,
 
 
 def DIV(classical_reg: MemoryReferenceDesignator,
-        right: MemoryReferenceOrImmediateValue) -> ClassicalDiv:
+        right: MRefDesignatorOrImmediateValue) -> ClassicalDiv:
     """
     Produce an DIV instruction.
 
@@ -729,7 +755,7 @@ def DIV(classical_reg: MemoryReferenceDesignator,
 
 def EQ(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MemoryReferenceOrImmediateValue) -> ClassicalEqual:
+       classical_reg3: MRefDesignatorOrImmediateValue) -> ClassicalEqual:
     """
     Produce an EQ instruction.
 
@@ -747,7 +773,7 @@ def EQ(classical_reg1: MemoryReferenceDesignator,
 
 def LT(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MemoryReferenceOrImmediateValue) -> ClassicalLessThan:
+       classical_reg3: MRefDesignatorOrImmediateValue) -> ClassicalLessThan:
     """
     Produce an LT instruction.
 
@@ -764,7 +790,7 @@ def LT(classical_reg1: MemoryReferenceDesignator,
 
 def LE(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MemoryReferenceOrImmediateValue) -> ClassicalLessEqual:
+       classical_reg3: MRefDesignatorOrImmediateValue) -> ClassicalLessEqual:
     """
     Produce an LE instruction.
 
@@ -781,7 +807,7 @@ def LE(classical_reg1: MemoryReferenceDesignator,
 
 def GT(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MemoryReferenceOrImmediateValue) -> ClassicalGreaterThan:
+       classical_reg3: MRefDesignatorOrImmediateValue) -> ClassicalGreaterThan:
     """
     Produce an GT instruction.
 
@@ -798,7 +824,7 @@ def GT(classical_reg1: MemoryReferenceDesignator,
 
 def GE(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MemoryReferenceOrImmediateValue) -> ClassicalGreaterEqual:
+       classical_reg3: MRefDesignatorOrImmediateValue) -> ClassicalGreaterEqual:
     """
     Produce an GE instruction.
 
diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index ae1a5a38d..df73d556a 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -104,10 +104,11 @@ def register(cls, n: int) -> List['QubitPlaceholder']:
         return [cls() for _ in range(n)]
 
 
+QubitOrPlaceholder = Union[Qubit, QubitPlaceholder]
 QubitDesignator = Union[Qubit, QubitPlaceholder, int]
 
 
-def unpack_qubit(qubit: QubitDesignator) -> Union[Qubit, QubitPlaceholder]:
+def unpack_qubit(qubit: QubitDesignator) -> QubitOrPlaceholder:
     """
     Get a qubit from an object.
 
@@ -127,8 +128,11 @@ def unpack_qubit(qubit: QubitDesignator) -> Union[Qubit, QubitPlaceholder]:
 # Like the Tuple, the List must be length 2, where the first item is a string and the second an
 # int. However, specifying Union[str, int] as the generic type argument to List doesn't sufficiently
 # constrain the types, and mypy gets confused in unpack_classical_reg, below. Hence, just specify
-# List here and add a "# type: ignore" comment to silence mypy --strict.
-MemoryReferenceDesignator = Union['MemoryReference', Tuple[str, int], List, str]  # type: ignore
+# List[Any] here.
+MemoryReferenceDesignator = Union['MemoryReference', Tuple[str, int], List[Any], str]
+MRefDesignatorOrImmediateInt = Union[MemoryReferenceDesignator, int]
+MRefDesignatorOrImmediateValue = Union[MemoryReferenceDesignator, int, float]
+MRefOrImmediateValue = Union['MemoryReference', int, float]
 
 
 def unpack_classical_reg(c: MemoryReferenceDesignator) -> 'MemoryReference':
@@ -202,6 +206,7 @@ def __hash__(self) -> int:
         return hash(id(self))
 
 
+LabelOrPlaceholder = Union[Label, LabelPlaceholder]
 ParameterDesignator = Union['Expression', 'MemoryReference', np.int_, int, float, complex]
 
 
diff --git a/pyquil/quilbase.py b/pyquil/quilbase.py
index af3c38b30..260659228 100644
--- a/pyquil/quilbase.py
+++ b/pyquil/quilbase.py
@@ -17,11 +17,19 @@
 Contains the core pyQuil objects that correspond to Quil instructions.
 """
 import numpy as np
+<<<<<<< HEAD
 from typing import Optional
+=======
+from six import integer_types, string_types
+from typing import Any, Callable, ClassVar, Dict, Iterable, List, Optional, Set, Tuple, Union
+>>>>>>> Add type annotations for the quilbase module
 from warnings import warn
 
-from pyquil.quilatom import (Expression, LabelPlaceholder, MemoryReference, Qubit, QubitPlaceholder,
-                             Label, _contained_parameters, format_parameter, unpack_qubit)
+from pyquil.quilatom import (Expression, ExpressionOrValue, Label, LabelPlaceholder,
+                             LabelOrPlaceholder, MemoryReference, MRefDesignatorOrImmediateInt,
+                             MRefDesignatorOrImmediateValue, Parameter, ParameterDesignator, Qubit,
+                             QubitDesignator, QubitOrPlaceholder, QubitPlaceholder,
+                             _contained_parameters, format_parameter, unpack_qubit)
 
 
 class AbstractInstruction(object):
@@ -29,57 +37,58 @@ class AbstractInstruction(object):
     Abstract class for representing single instructions.
     """
 
-    def out(self):
+    def out(self) -> str:
         pass
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.out()
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return isinstance(other, self.__class__) and self.out() == other.out()
 
-    def __ne__(self, other):
+    def __ne__(self, other: object) -> bool:
         return not self.__eq__(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.out())
 
 
-RESERVED_WORDS = ['DEFGATE', 'DEFCIRCUIT', 'MEASURE',
-                  'LABEL', 'HALT', 'JUMP', 'JUMP-WHEN', 'JUMP-UNLESS',
-                  'RESET', 'WAIT', 'NOP', 'INCLUDE', 'PRAGMA',
-                  'DECLARE',
-                  'NEG', 'NOT', 'AND', 'IOR', 'XOR',
-                  'MOVE', 'EXCHANGE', 'CONVERT',
-                  'ADD', 'SUB', 'MUL', 'DIV',
-                  'EQ', 'GT', 'GE', 'LT', 'LE',
-                  'LOAD', 'STORE',
-                  # to be removed:
-                  'TRUE', 'FALSE', 'OR'
-                  ]
+RESERVED_WORDS: List[str] = [
+    'DEFGATE', 'DEFCIRCUIT', 'MEASURE',
+    'LABEL', 'HALT', 'JUMP', 'JUMP-WHEN', 'JUMP-UNLESS',
+    'RESET', 'WAIT', 'NOP', 'INCLUDE', 'PRAGMA',
+    'DECLARE',
+    'NEG', 'NOT', 'AND', 'IOR', 'XOR',
+    'MOVE', 'EXCHANGE', 'CONVERT',
+    'ADD', 'SUB', 'MUL', 'DIV',
+    'EQ', 'GT', 'GE', 'LT', 'LE',
+    'LOAD', 'STORE',
+    # to be removed:
+    'TRUE', 'FALSE', 'OR'
+]
 
 
-def _extract_qubit_index(qubit, index=True):
+def _extract_qubit_index(qubit: QubitOrPlaceholder, index: bool = True) -> QubitDesignator:
     if (not index) or isinstance(qubit, QubitPlaceholder):
         return qubit
     return qubit.index
 
 
-def _format_qubit_str(qubit):
+def _format_qubit_str(qubit: QubitOrPlaceholder) -> str:
     if isinstance(qubit, QubitPlaceholder):
         return "{%s}" % str(qubit)
     return str(qubit)
 
 
-def _format_qubits_str(qubits):
+def _format_qubits_str(qubits: List[QubitOrPlaceholder]) -> str:
     return " ".join([_format_qubit_str(qubit) for qubit in qubits])
 
 
-def _format_qubits_out(qubits):
+def _format_qubits_out(qubits: List[QubitOrPlaceholder]) -> str:
     return " ".join([qubit.out() for qubit in qubits])
 
 
-def _format_params(params):
+def _format_params(params: Iterable[ParameterDesignator]) -> str:
     return "(" + ",".join(format_parameter(param) for param in params) + ")"
 
 
@@ -88,13 +97,9 @@ class Gate(AbstractInstruction):
     This is the pyQuil object for a quantum gate instruction.
     """
 
-<<<<<<< HEAD
-    def __init__(self, name, params, qubits):
+    def __init__(self, name: str, params: List[ParameterDesignator],
+                 qubits: List[QubitOrPlaceholder]):
         if not isinstance(name, str):
-=======
-    def __init__(self, name, params, qubits) -> None:
-        if not isinstance(name, string_types):
->>>>>>> Satisfy mypy --strict about pyquil.quilatom type hints
             raise TypeError("Gate name must be a string")
 
         if name in RESERVED_WORDS:
@@ -112,12 +117,12 @@ def __init__(self, name, params, qubits) -> None:
         self.name = name
         self.params = params
         self.qubits = qubits
-        self.modifiers = []
+        self.modifiers: List[str] = []
 
-    def get_qubits(self, indices=True):
+    def get_qubits(self, indices: bool = True) -> Set[QubitDesignator]:
         return {_extract_qubit_index(q, indices) for q in self.qubits}
 
-    def out(self):
+    def out(self) -> str:
         if self.params:
             return "{}{}{} {}".format(
                 ' '.join(self.modifiers) + ' ' if self.modifiers else '',
@@ -128,7 +133,7 @@ def out(self):
                 ' '.join(self.modifiers) + ' ' if self.modifiers else '',
                 self.name, _format_qubits_out(self.qubits))
 
-    def controlled(self, control_qubit):
+    def controlled(self, control_qubit: QubitDesignator) -> 'Gate':
         """
         Add the CONTROLLED modifier to the gate with the given control qubit.
         """
@@ -139,7 +144,7 @@ def controlled(self, control_qubit):
 
         return self
 
-    def forked(self, fork_qubit, alt_params):
+    def forked(self, fork_qubit: QubitDesignator, alt_params: List[ParameterDesignator]) -> 'Gate':
         """
         Add the FORKED modifier to the gate with the given fork qubit and given additional parameters.
         """
@@ -156,7 +161,7 @@ def forked(self, fork_qubit, alt_params):
 
         return self
 
-    def dagger(self):
+    def dagger(self) -> 'Gate':
         """
         Add the DAGGER modifier to the gate.
         """
@@ -164,10 +169,10 @@ def dagger(self):
 
         return self
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<Gate " + str(self) + ">"
 
-    def __str__(self):
+    def __str__(self) -> str:
         if self.params:
             return "{}{}{} {}".format(
                 ' '.join(self.modifiers) + ' ' if self.modifiers else '',
@@ -179,7 +184,7 @@ def __str__(self):
                 self.name, _format_qubits_str(self.qubits))
 
 
-def _strip_modifiers(gate: Gate, limit: Optional[int] = None):
+def _strip_modifiers(gate: Gate, limit: Optional[int] = None) -> Gate:
     """
     Remove modifiers from :py:class:`Gate`.
 
@@ -225,28 +230,28 @@ class Measurement(AbstractInstruction):
     This is the pyQuil object for a Quil measurement instruction.
     """
 
-    def __init__(self, qubit, classical_reg) -> None:
+    def __init__(self, qubit: QubitOrPlaceholder, classical_reg: Optional[MemoryReference]):
         if not isinstance(qubit, (Qubit, QubitPlaceholder)):
             raise TypeError("qubit should be a Qubit")
-        if classical_reg and not isinstance(classical_reg, MemoryReference):
+        if classical_reg is not None and not isinstance(classical_reg, MemoryReference):
             raise TypeError("classical_reg should be None or a MemoryReference instance")
 
         self.qubit = qubit
         self.classical_reg = classical_reg
 
-    def out(self):
+    def out(self) -> str:
         if self.classical_reg:
             return "MEASURE {} {}".format(self.qubit.out(), self.classical_reg.out())
         else:
             return "MEASURE {}".format(self.qubit.out())
 
-    def __str__(self):
+    def __str__(self) -> str:
         if self.classical_reg:
             return "MEASURE {} {}".format(_format_qubit_str(self.qubit), str(self.classical_reg))
         else:
             return "MEASURE {}".format(_format_qubit_str(self.qubit))
 
-    def get_qubits(self, indices=True):
+    def get_qubits(self, indices: bool = True) -> Set[QubitDesignator]:
         return {_extract_qubit_index(self.qubit, indices)}
 
 
@@ -255,18 +260,18 @@ class ResetQubit(AbstractInstruction):
     This is the pyQuil object for a Quil targeted reset instruction.
     """
 
-    def __init__(self, qubit) -> None:
+    def __init__(self, qubit: QubitOrPlaceholder):
         if not isinstance(qubit, (Qubit, QubitPlaceholder)):
             raise TypeError("qubit should be a Qubit")
         self.qubit = qubit
 
-    def out(self):
+    def out(self) -> str:
         return "RESET {}".format(self.qubit.out())
 
-    def __str__(self):
+    def __str__(self) -> str:
         return "RESET {}".format(_format_qubit_str(self.qubit))
 
-    def get_qubits(self, indices=True):
+    def get_qubits(self, indices: bool = True) -> Set[QubitDesignator]:
         return {_extract_qubit_index(self.qubit, indices)}
 
 
@@ -274,12 +279,13 @@ class DefGate(AbstractInstruction):
     """
     A DEFGATE directive.
 
-    :param string name: The name of the newly defined gate.
-    :param array-like matrix: {list, nparray, np.matrix} The matrix defining this gate.
-    :param list parameters: list of parameters that are used in this gate
+    :param name: The name of the newly defined gate.
+    :param matrix: The matrix defining this gate.
+    :param parameters: list of parameters that are used in this gate
     """
 
-    def __init__(self, name, matrix, parameters=None) -> None:
+    def __init__(self, name: str, matrix: Union[List[List[Any]], np.ndarray, np.matrix],
+                 parameters: Optional[List[Parameter]] = None):
         if not isinstance(name, str):
             raise TypeError("Gate name must be a string")
 
@@ -319,14 +325,13 @@ def __init__(self, name, matrix, parameters=None) -> None:
 
         self.parameters = parameters
 
-    def out(self):
+    def out(self) -> str:
         """
         Prints a readable Quil string representation of this gate.
 
         :returns: String representation of a gate
-        :rtype: string
         """
-        def format_matrix_element(element):
+        def format_matrix_element(element: Union[ExpressionOrValue, str]) -> str:
             """
             Formats a parameterized matrix element.
 
@@ -353,7 +358,7 @@ def format_matrix_element(element):
             result += "\n"
         return result
 
-    def get_constructor(self):
+    def get_constructor(self) -> Union[Callable[..., Gate], Callable[..., Callable[..., Gate]]]:
         """
         :returns: A function that constructs this gate on variable qubit indices. E.g.
                   `mygate.get_constructor()(1) applies the gate to qubit 1.`
@@ -364,17 +369,16 @@ def get_constructor(self):
         else:
             return lambda *qubits: Gate(name=self.name, params=[], qubits=list(map(unpack_qubit, qubits)))
 
-    def num_args(self):
+    def num_args(self) -> int:
         """
         :return: The number of qubit arguments the gate takes.
-        :rtype: int
         """
         rows = len(self.matrix)
         return int(np.log2(rows))
 
 
 class DefPermutationGate(DefGate):
-    def __init__(self, name, permutation) -> None:
+    def __init__(self, name: str, permutation: Union[List[Union[int, np.int_]], np.ndarray]):
         if not isinstance(name, str):
             raise TypeError("Gate name must be a string")
 
@@ -397,14 +401,13 @@ def __init__(self, name, permutation) -> None:
         self.permutation = np.asarray(permutation)
         self.parameters = None
 
-    def out(self):
+    def out(self) -> str:
         body = ', '.join([str(p) for p in self.permutation])
         return f"DEFGATE {self.name} AS PERMUTATION:\n    {body}"
 
-    def num_args(self):
+    def num_args(self) -> int:
         """
         :return: The number of qubit arguments the gate takes.
-        :rtype: int
         """
         return int(np.log2(len(self.permutation)))
 
@@ -414,15 +417,15 @@ class JumpTarget(AbstractInstruction):
     Representation of a target that can be jumped to.
     """
 
-    def __init__(self, label) -> None:
+    def __init__(self, label: LabelOrPlaceholder):
         if not isinstance(label, (Label, LabelPlaceholder)):
             raise TypeError("label must be a Label")
         self.label = label
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<JumpTarget {0}>".format(str(self.label))
 
-    def out(self):
+    def out(self) -> str:
         return "LABEL {0}".format(str(self.label))
 
 
@@ -430,9 +433,9 @@ class JumpConditional(AbstractInstruction):
     """
     Abstract representation of an conditional jump instruction.
     """
-    op = NotImplemented
+    op: ClassVar[str]
 
-    def __init__(self, target, condition) -> None:
+    def __init__(self, target: LabelOrPlaceholder, condition: MemoryReference):
         if not isinstance(target, (Label, LabelPlaceholder)):
             raise TypeError("target should be a Label")
         if not isinstance(condition, MemoryReference):
@@ -440,7 +443,7 @@ def __init__(self, target, condition) -> None:
         self.target = target
         self.condition = condition
 
-    def out(self):
+    def out(self) -> str:
         return "%s %s %s" % (self.op, self.target, self.condition)
 
 
@@ -462,8 +465,9 @@ class SimpleInstruction(AbstractInstruction):
     """
     Abstract class for simple instructions with no arguments.
     """
+    op: ClassVar[str]
 
-    def out(self):
+    def out(self) -> str:
         return self.op
 
 
@@ -499,13 +503,14 @@ class UnaryClassicalInstruction(AbstractInstruction):
     """
     The abstract class for unary classical instructions.
     """
+    op: ClassVar[str]
 
-    def __init__(self, target) -> None:
+    def __init__(self, target: MemoryReference):
         if not isinstance(target, MemoryReference):
             raise TypeError("target operand should be an MemoryReference")
         self.target = target
 
-    def out(self):
+    def out(self) -> str:
         return "%s %s" % (self.op, self.target)
 
 
@@ -527,9 +532,9 @@ class LogicalBinaryOp(AbstractInstruction):
     """
     The abstract class for binary logical classical instructions.
     """
-    op = NotImplemented
+    op: ClassVar[str]
 
-    def __init__(self, left, right) -> None:
+    def __init__(self, left: MemoryReference, right: MRefDesignatorOrImmediateInt):
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference) and not isinstance(right, int):
@@ -537,7 +542,7 @@ def __init__(self, left, right) -> None:
         self.left = left
         self.right = right
 
-    def out(self):
+    def out(self) -> str:
         return "%s %s %s" % (self.op, self.left, self.right)
 
 
@@ -574,7 +579,7 @@ class ClassicalOr(ClassicalInclusiveOr):
     Deprecated class.
     """
 
-    def __init__(self, left, right) -> None:
+    def __init__(self, left: MemoryReference, right: MemoryReference):
         warn("ClassicalOr has been deprecated. Replacing with "
              "ClassicalInclusiveOr. Use ClassicalInclusiveOr instead. "
              "NOTE: The operands to ClassicalInclusiveOr are inverted from "
@@ -586,8 +591,9 @@ class ArithmeticBinaryOp(AbstractInstruction):
     """
     The abstract class for binary arithmetic classical instructions.
     """
+    op: ClassVar[str]
 
-    def __init__(self, left, right) -> None:
+    def __init__(self, left: MemoryReference, right: MRefDesignatorOrImmediateValue):
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference) and not isinstance(right, int) and not isinstance(right, float):
@@ -595,7 +601,7 @@ def __init__(self, left, right) -> None:
         self.left = left
         self.right = right
 
-    def out(self):
+    def out(self) -> str:
         return "%s %s %s" % (self.op, self.left, self.right)
 
 
@@ -637,7 +643,7 @@ class ClassicalMove(AbstractInstruction):
     """
     op = "MOVE"
 
-    def __init__(self, left, right) -> None:
+    def __init__(self, left: MemoryReference, right: MRefDesignatorOrImmediateValue):
         if not isinstance(left, MemoryReference):
             raise TypeError("Left operand of MOVE should be an MemoryReference.  "
                             "Note that the order of the operands in pyQuil 2.0 has reversed from "
@@ -648,7 +654,7 @@ def __init__(self, left, right) -> None:
         self.left = left
         self.right = right
 
-    def out(self):
+    def out(self) -> str:
         return "%s %s %s" % (self.op, self.left, self.right)
 
 
@@ -657,7 +663,7 @@ class ClassicalFalse(ClassicalMove):
     Deprecated class.
     """
 
-    def __init__(self, target) -> None:
+    def __init__(self, target: MemoryReference):
         super().__init__(target, 0)
         warn("ClassicalFalse is deprecated in favor of ClassicalMove.")
 
@@ -667,7 +673,7 @@ class ClassicalTrue(ClassicalMove):
     Deprecated class.
     """
 
-    def __init__(self, target) -> None:
+    def __init__(self, target: MemoryReference):
         super().__init__(target, 1)
         warn("ClassicalTrue is deprecated in favor of ClassicalMove.")
 
@@ -679,7 +685,7 @@ class ClassicalExchange(AbstractInstruction):
 
     op = "EXCHANGE"
 
-    def __init__(self, left, right) -> None:
+    def __init__(self, left: MemoryReference, right: MemoryReference):
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference):
@@ -687,7 +693,7 @@ def __init__(self, left, right) -> None:
         self.left = left
         self.right = right
 
-    def out(self):
+    def out(self) -> str:
         return "%s %s %s" % (self.op, self.left, self.right)
 
 
@@ -698,7 +704,7 @@ class ClassicalConvert(AbstractInstruction):
 
     op = "CONVERT"
 
-    def __init__(self, left, right) -> None:
+    def __init__(self, left: MemoryReference, right: MemoryReference):
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference):
@@ -706,7 +712,7 @@ def __init__(self, left, right) -> None:
         self.left = left
         self.right = right
 
-    def out(self):
+    def out(self) -> str:
         return "%s %s %s" % (self.op, self.left, self.right)
 
 
@@ -717,7 +723,7 @@ class ClassicalLoad(AbstractInstruction):
 
     op = "LOAD"
 
-    def __init__(self, target, left, right) -> None:
+    def __init__(self, target: MemoryReference, left: str, right: MemoryReference):
         if not isinstance(target, MemoryReference):
             raise TypeError("target operand should be an MemoryReference")
         if not isinstance(right, MemoryReference):
@@ -726,7 +732,7 @@ def __init__(self, target, left, right) -> None:
         self.left = left
         self.right = right
 
-    def out(self):
+    def out(self) -> str:
         return "%s %s %s %s" % (self.op, self.target, self.left, self.right)
 
 
@@ -737,7 +743,7 @@ class ClassicalStore(AbstractInstruction):
 
     op = "STORE"
 
-    def __init__(self, target, left, right) -> None:
+    def __init__(self, target: str, left: MemoryReference, right: MRefDesignatorOrImmediateValue):
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not (isinstance(right, MemoryReference) or isinstance(right, int)
@@ -747,7 +753,7 @@ def __init__(self, target, left, right) -> None:
         self.left = left
         self.right = right
 
-    def out(self):
+    def out(self) -> str:
         return "%s %s %s %s" % (self.op, self.target, self.left, self.right)
 
 
@@ -755,17 +761,22 @@ class ClassicalComparison(AbstractInstruction):
     """
     Abstract class for ternary comparison instructions.
     """
+    op: ClassVar[str]
 
-    def __init__(self, target, left, right) -> None:
+    def __init__(self, target: MemoryReference, left: MemoryReference,
+                 right: MRefDesignatorOrImmediateValue):
         if not isinstance(target, MemoryReference):
             raise TypeError("target operand should be an MemoryReference")
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
+        if not (isinstance(right, MemoryReference) or isinstance(right, int)
+                or isinstance(right, float)):
+            raise TypeError("right operand should be an MemoryReference or an int or float.")
         self.target = target
         self.left = left
         self.right = right
 
-    def out(self):
+    def out(self) -> str:
         return "%s %s %s %s" % (self.op, self.target, self.left, self.right)
 
 
@@ -814,12 +825,12 @@ class Jump(AbstractInstruction):
     Representation of an unconditional jump instruction (JUMP).
     """
 
-    def __init__(self, target) -> None:
+    def __init__(self, target: LabelOrPlaceholder):
         if not isinstance(target, (Label, LabelPlaceholder)):
             raise TypeError("target should be a Label")
         self.target = target
 
-    def out(self):
+    def out(self) -> str:
         return "JUMP %s" % self.target
 
 
@@ -833,12 +844,15 @@ class Pragma(AbstractInstruction):
 
     """
 
-    def __init__(self, command, args=(), freeform_string="") -> None:
+    def __init__(self, command: str,
+                 args: Union[List[Union[QubitDesignator, str]],
+                             Tuple[Union[QubitDesignator, str], ...]] = (),
+                 freeform_string: str = ""):
         if not isinstance(command, str):
             raise TypeError("Pragma's require an identifier.")
 
         if not isinstance(args, (tuple, list)):
-            raise TypeError("Pragma arguments must be a list: {}".format(args))
+            raise TypeError("Pragma arguments must be a list or tuple: {}".format(args))
         for a in args:
             if not (isinstance(a, str)
                     or isinstance(a, int)
@@ -853,7 +867,7 @@ def __init__(self, command, args=(), freeform_string="") -> None:
         self.args = args
         self.freeform_string = freeform_string
 
-    def out(self):
+    def out(self) -> str:
         ret = "PRAGMA {}".format(self.command)
         if self.args:
             ret += " {}".format(" ".join(str(a) for a in self.args))
@@ -861,10 +875,13 @@ def out(self):
             ret += " \"{}\"".format(self.freeform_string)
         return ret
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return '<PRAGMA {}>'.format(self.command)
 
 
+DeclareOffsets = List[Tuple[int, str]]
+
+
 class Declare(AbstractInstruction):
     """
     A DECLARE directive.
@@ -875,7 +892,9 @@ class Declare(AbstractInstruction):
 
     """
 
-    def __init__(self, name, memory_type, memory_size=1, shared_region=None, offsets=None) -> None:
+    def __init__(self, name: str, memory_type: str, memory_size: int = 1,
+                 shared_region: Optional[str] = None,
+                 offsets: Optional[DeclareOffsets] = None):
         self.name = name
         self.memory_type = memory_type
         self.memory_size = memory_size
@@ -885,7 +904,7 @@ def __init__(self, name, memory_type, memory_size=1, shared_region=None, offsets
             offsets = []
         self.offsets = offsets
 
-    def asdict(self):
+    def asdict(self) -> Dict[str, Union[DeclareOffsets, Optional[str], int]]:
         return {
             'name': self.name,
             'memory_type': self.memory_type,
@@ -894,7 +913,7 @@ def asdict(self):
             'offsets': self.offsets,
         }
 
-    def out(self):
+    def out(self) -> str:
         ret = "DECLARE {} {}[{}]".format(self.name, self.memory_type, self.memory_size)
         if self.shared_region:
             ret += " SHARING {}".format(self.shared_region)
@@ -903,7 +922,7 @@ def out(self):
 
         return ret
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return '<DECLARE {}>'.format(self.name)
 
 
@@ -912,13 +931,13 @@ class RawInstr(AbstractInstruction):
     A raw instruction represented as a string.
     """
 
-    def __init__(self, instr_str) -> None:
+    def __init__(self, instr_str: str):
         if not isinstance(instr_str, str):
             raise TypeError("Raw instructions require a string.")
         self.instr = instr_str
 
-    def out(self):
+    def out(self) -> str:
         return self.instr
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return '<RawInstr {}>'.format(self.instr)

From 8268edbd8010260a12a4f6322de11353afd18011 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Wed, 9 Oct 2019 15:18:03 -0500
Subject: [PATCH 13/25] Nix return type hints for __init__ methods in
 quilatom.py

---
 pyquil/quilatom.py | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index df73d556a..8c78f35b8 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -47,7 +47,7 @@ class Qubit(QuilAtom):
     :param int index: Index of the qubit.
     """
 
-    def __init__(self, index: int) -> None:
+    def __init__(self, index: int):
         if not (isinstance(index, int) and index >= 0):
             raise TypeError("Addr index must be a non-negative int")
         self.index = index
@@ -167,7 +167,7 @@ class Label(QuilAtom):
     :param string label_name: The label name.
     """
 
-    def __init__(self, label_name: str) -> None:
+    def __init__(self, label_name: str):
         self.name = label_name
 
     def out(self) -> str:
@@ -187,7 +187,7 @@ def __hash__(self) -> int:
 
 
 class LabelPlaceholder(QuilAtom):
-    def __init__(self, prefix: str = "L") -> None:
+    def __init__(self, prefix: str = "L"):
         self.prefix = prefix
 
     def out(self) -> str:
@@ -349,7 +349,7 @@ class Parameter(QuilAtom, Expression):
     Parameters in Quil are represented as a label like '%x' for the parameter named 'x'.
     """
 
-    def __init__(self, name: str) -> None:
+    def __init__(self, name: str):
         self.name = name
 
     def out(self) -> str:
@@ -373,7 +373,7 @@ class Function(Expression):
     Supported functions in Quil are sin, cos, sqrt, exp, and cis
     """
     def __init__(self, name: str, expression: ExpressionOrValue,
-                 fn: Callable[[ExpressionValue], ExpressionValue]) -> None:
+                 fn: Callable[[ExpressionValue], ExpressionValue]):
         self.name = name
         self.expression = expression
         self.fn = fn
@@ -422,7 +422,7 @@ class BinaryExp(Expression):
     def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['BinaryExp', ExpressionValue]:
         raise NotImplementedError
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
         self.op1 = op1
         self.op2 = op2
 
@@ -448,7 +448,7 @@ class Add(BinaryExp):
     def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Add', ExpressionValue]:
         return a + b
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
         super(Add, self).__init__(op1, op2)
 
 
@@ -461,7 +461,7 @@ class Sub(BinaryExp):
     def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Sub', ExpressionValue]:
         return a - b
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
         super(Sub, self).__init__(op1, op2)
 
 
@@ -474,7 +474,7 @@ class Mul(BinaryExp):
     def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Mul', ExpressionValue]:
         return a * b
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
         super(Mul, self).__init__(op1, op2)
 
 
@@ -487,7 +487,7 @@ class Div(BinaryExp):
     def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Div', ExpressionValue]:
         return a / b
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
         super(Div, self).__init__(op1, op2)
 
 
@@ -500,7 +500,7 @@ class Pow(BinaryExp):
     def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Pow', ExpressionValue]:
         return a ** b
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue) -> None:
+    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
         super(Pow, self).__init__(op1, op2)
 
 
@@ -600,7 +600,7 @@ class MemoryReference(QuilAtom, Expression):
         the declared variable is of length >1 or 1, resp.
     """
 
-    def __init__(self, name: str, offset: int = 0, declared_size: Optional[int] = None) -> None:
+    def __init__(self, name: str, offset: int = 0, declared_size: Optional[int] = None):
         if not isinstance(offset, int) or offset < 0:
             raise TypeError("MemoryReference offset must be a non-negative int")
         self.name = name
@@ -654,7 +654,7 @@ class Addr(MemoryReference):
     :param int value: The classical address.
     """
 
-    def __init__(self, value: int) -> None:
+    def __init__(self, value: int):
         warn("Addr objects have been deprecated. Defaulting to memory region \"ro\". Use MemoryReference instead.")
         if not isinstance(value, int) or value < 0:
             raise TypeError("Addr value must be a non-negative int")

From 5db4522a8e0d87cf7772250f03e40d47afc912f4 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Wed, 9 Oct 2019 17:11:35 -0500
Subject: [PATCH 14/25] Replace List types with more generic container types
 where possible

---
 pyquil/quilatom.py |  6 +++---
 pyquil/quilbase.py | 47 +++++++++++++++++++++++-----------------------
 2 files changed, 27 insertions(+), 26 deletions(-)

diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index 8c78f35b8..8552205b8 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -16,7 +16,7 @@
 import numpy as np
 from warnings import warn
 from fractions import Fraction
-from typing import Any, Callable, ClassVar, Dict, List, Optional, Set, Tuple, Union
+from typing import Any, Callable, ClassVar, Dict, List, Optional, Set, Sequence, Tuple, Union
 
 
 class QuilAtom(object):
@@ -330,12 +330,12 @@ def substitute(expr: ExpressionOrValue, d: ParameterSubstitutionsDict) -> Expres
     return expr
 
 
-def substitute_array(a: Union[List[Expression], np.array],
+def substitute_array(a: Union[Sequence[Expression], np.array],
                      d: ParameterSubstitutionsDict) -> np.array:
     """
     Apply ``substitute`` to all elements of an array ``a`` and return the resulting array.
 
-    :param Union[np.array,List] a: The expression array to substitute.
+    :param Union[np.array,Sequence[Expression]] a: The expression array to substitute.
     :param Dict[Parameter,Union[int,float]] d: Numerical substitutions for parameters.
     :return: An array of partially substituted Expressions or numbers.
     :rtype: np.array
diff --git a/pyquil/quilbase.py b/pyquil/quilbase.py
index 260659228..aae40960c 100644
--- a/pyquil/quilbase.py
+++ b/pyquil/quilbase.py
@@ -16,13 +16,10 @@
 """
 Contains the core pyQuil objects that correspond to Quil instructions.
 """
+import collections
 import numpy as np
-<<<<<<< HEAD
-from typing import Optional
-=======
-from six import integer_types, string_types
-from typing import Any, Callable, ClassVar, Dict, Iterable, List, Optional, Set, Tuple, Union
->>>>>>> Add type annotations for the quilbase module
+from typing import (Any, Callable, ClassVar, Container, Dict, Iterable, List, Optional, Set, Tuple,
+                    Union)
 from warnings import warn
 
 from pyquil.quilatom import (Expression, ExpressionOrValue, Label, LabelPlaceholder,
@@ -53,7 +50,7 @@ def __hash__(self) -> int:
         return hash(self.out())
 
 
-RESERVED_WORDS: List[str] = [
+RESERVED_WORDS: Container[str] = [
     'DEFGATE', 'DEFCIRCUIT', 'MEASURE',
     'LABEL', 'HALT', 'JUMP', 'JUMP-WHEN', 'JUMP-UNLESS',
     'RESET', 'WAIT', 'NOP', 'INCLUDE', 'PRAGMA',
@@ -80,11 +77,11 @@ def _format_qubit_str(qubit: QubitOrPlaceholder) -> str:
     return str(qubit)
 
 
-def _format_qubits_str(qubits: List[QubitOrPlaceholder]) -> str:
+def _format_qubits_str(qubits: Iterable[QubitOrPlaceholder]) -> str:
     return " ".join([_format_qubit_str(qubit) for qubit in qubits])
 
 
-def _format_qubits_out(qubits: List[QubitOrPlaceholder]) -> str:
+def _format_qubits_out(qubits: Iterable[QubitOrPlaceholder]) -> str:
     return " ".join([qubit.out() for qubit in qubits])
 
 
@@ -97,26 +94,31 @@ class Gate(AbstractInstruction):
     This is the pyQuil object for a quantum gate instruction.
     """
 
-    def __init__(self, name: str, params: List[ParameterDesignator],
-                 qubits: List[QubitOrPlaceholder]):
+    def __init__(self, name: str, params: Iterable[ParameterDesignator],
+                 qubits: Iterable[QubitOrPlaceholder]):
         if not isinstance(name, str):
             raise TypeError("Gate name must be a string")
 
         if name in RESERVED_WORDS:
             raise ValueError("Cannot use {} for a gate name since it's a reserved word".format(name))
 
-        if not isinstance(params, list):
-            raise TypeError("Gate params must be a list")
+        if not isinstance(params, collections.abc.Iterable):
+            raise TypeError("Gate params must be an Iterable")
+
+        if not isinstance(qubits, collections.abc.Iterable):
+            raise TypeError("Gate arguments must be an Iterable")
 
-        if not isinstance(qubits, list) or not qubits:
-            raise TypeError("Gate arguments must be a non-empty list")
         for qubit in qubits:
             if not isinstance(qubit, (Qubit, QubitPlaceholder)):
                 raise TypeError("Gate arguments must all be Qubits")
 
+        qubits_list = list(qubits)
+        if len(qubits_list) == 0:
+            raise TypeError("Gate arguments must be non-empty")
+
         self.name = name
-        self.params = params
-        self.qubits = qubits
+        self.params = list(params)
+        self.qubits = qubits_list
         self.modifiers: List[str] = []
 
     def get_qubits(self, indices: bool = True) -> Set[QubitDesignator]:
@@ -845,14 +847,13 @@ class Pragma(AbstractInstruction):
     """
 
     def __init__(self, command: str,
-                 args: Union[List[Union[QubitDesignator, str]],
-                             Tuple[Union[QubitDesignator, str], ...]] = (),
+                 args: Iterable[Union[QubitDesignator, str]] = (),
                  freeform_string: str = ""):
         if not isinstance(command, str):
             raise TypeError("Pragma's require an identifier.")
 
-        if not isinstance(args, (tuple, list)):
-            raise TypeError("Pragma arguments must be a list or tuple: {}".format(args))
+        if not isinstance(args, collections.abc.Iterable):
+            raise TypeError("Pragma arguments must be an Iterable: {}".format(args))
         for a in args:
             if not (isinstance(a, str)
                     or isinstance(a, int)
@@ -864,7 +865,7 @@ def __init__(self, command: str,
                 freeform_string))
 
         self.command = command
-        self.args = args
+        self.args = tuple(args)
         self.freeform_string = freeform_string
 
     def out(self) -> str:
@@ -879,7 +880,7 @@ def __repr__(self) -> str:
         return '<PRAGMA {}>'.format(self.command)
 
 
-DeclareOffsets = List[Tuple[int, str]]
+DeclareOffsets = Iterable[Tuple[int, str]]
 
 
 class Declare(AbstractInstruction):

From 9cd30ce581b51b6f4febc91594906885b750d7ca Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Wed, 9 Oct 2019 17:25:39 -0500
Subject: [PATCH 15/25] Replace Dict types with more generic container types
 where possible

---
 pyquil/gates.py    |  6 +++---
 pyquil/quilatom.py | 18 +++++++++---------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index eb00c0507..f074b9a40 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -14,7 +14,7 @@
 #    limitations under the License.
 ##############################################################################
 from warnings import warn
-from typing import Any, Callable, Dict, Optional, Tuple, Union, overload
+from typing import Any, Callable, Mapping, Optional, Tuple, Union, overload
 
 from pyquil.quilatom import (Addr, Expression, MemoryReference, MemoryReferenceDesignator,
                              MRefDesignatorOrImmediateInt, MRefDesignatorOrImmediateValue,
@@ -839,7 +839,7 @@ def GE(classical_reg1: MemoryReferenceDesignator,
     return ClassicalGreaterEqual(classical_reg1, classical_reg2, classical_reg3)
 
 
-QUANTUM_GATES: Dict[str, Callable[..., Gate]] = {
+QUANTUM_GATES: Mapping[str, Callable[..., Gate]] = {
     'I': I,
     'X': X,
     'Y': Y,
@@ -871,7 +871,7 @@ def GE(classical_reg1: MemoryReferenceDesignator,
 Alias for the above dictionary of quantum gates.
 """
 
-STANDARD_INSTRUCTIONS: Dict[str, Union[AbstractInstruction, Callable[..., AbstractInstruction]]] = {
+STANDARD_INSTRUCTIONS: Mapping[str, Union[AbstractInstruction, Callable[..., AbstractInstruction]]] = {
     'WAIT': WAIT,
     'RESET': RESET,
     'NOP': NOP,
diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index 8552205b8..2548fe6cf 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -16,7 +16,7 @@
 import numpy as np
 from warnings import warn
 from fractions import Fraction
-from typing import Any, Callable, ClassVar, Dict, List, Optional, Set, Sequence, Tuple, Union
+from typing import Any, Callable, ClassVar, List, Mapping, Optional, Set, Sequence, Tuple, Union
 
 
 class QuilAtom(object):
@@ -312,16 +312,16 @@ def _substitute(self, d: Any) -> 'ExpressionOrValue':
         return self
 
 
-ParameterSubstitutionsDict = Dict['Parameter', ExpressionValue]
+ParameterSubstitutionsMap = Mapping['Parameter', ExpressionValue]
 
 
-def substitute(expr: ExpressionOrValue, d: ParameterSubstitutionsDict) -> ExpressionOrValue:
+def substitute(expr: ExpressionOrValue, d: ParameterSubstitutionsMap) -> ExpressionOrValue:
     """
     Using a dictionary of substitutions ``d`` try and explicitly evaluate as much of ``expr`` as
     possible.
 
     :param Expression expr: The expression whose parameters are substituted.
-    :param Dict[Parameter,Union[int,float]] d: Numerical substitutions for parameters.
+    :param Mapping[Parameter,Union[int,float]] d: Numerical substitutions for parameters.
     :return: A partially simplified Expression or a number.
     :rtype: Union[Expression,int,float]
     """
@@ -331,12 +331,12 @@ def substitute(expr: ExpressionOrValue, d: ParameterSubstitutionsDict) -> Expres
 
 
 def substitute_array(a: Union[Sequence[Expression], np.array],
-                     d: ParameterSubstitutionsDict) -> np.array:
+                     d: ParameterSubstitutionsMap) -> np.array:
     """
     Apply ``substitute`` to all elements of an array ``a`` and return the resulting array.
 
     :param Union[np.array,Sequence[Expression]] a: The expression array to substitute.
-    :param Dict[Parameter,Union[int,float]] d: Numerical substitutions for parameters.
+    :param Mapping[Parameter,Union[int,float]] d: Numerical substitutions for parameters.
     :return: An array of partially substituted Expressions or numbers.
     :rtype: np.array
     """
@@ -355,7 +355,7 @@ def __init__(self, name: str):
     def out(self) -> str:
         return '%' + self.name
 
-    def _substitute(self, d: ParameterSubstitutionsDict) -> Union['Parameter', ExpressionValue]:
+    def _substitute(self, d: ParameterSubstitutionsMap) -> Union['Parameter', ExpressionValue]:
         return d.get(self, self)
 
     def __str__(self) -> str:
@@ -378,7 +378,7 @@ def __init__(self, name: str, expression: ExpressionOrValue,
         self.expression = expression
         self.fn = fn
 
-    def _substitute(self, d: ParameterSubstitutionsDict) -> Union['Function', ExpressionValue]:
+    def _substitute(self, d: ParameterSubstitutionsMap) -> Union['Function', ExpressionValue]:
         sop = substitute(self.expression, d)
         if isinstance(sop, Expression):
             return Function(self.name, sop, self.fn)
@@ -426,7 +426,7 @@ def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
         self.op1 = op1
         self.op2 = op2
 
-    def _substitute(self, d: ParameterSubstitutionsDict) -> Union['BinaryExp', ExpressionValue]:
+    def _substitute(self, d: ParameterSubstitutionsMap) -> Union['BinaryExp', ExpressionValue]:
         sop1, sop2 = substitute(self.op1, d), substitute(self.op2, d)
         return self.fn(sop1, sop2)
 

From 2b39dbcb0a5f55fb5b6542764cd3fa6de8c518ce Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Wed, 9 Oct 2019 17:38:31 -0500
Subject: [PATCH 16/25] Remove types from docstrings

---
 pyquil/gates.py    |  4 ++--
 pyquil/quilatom.py | 22 +++++++++-------------
 pyquil/quilbase.py |  2 +-
 3 files changed, 12 insertions(+), 16 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index f074b9a40..6e043e831 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -425,8 +425,8 @@ def CSWAP(control: QubitDesignator, target_1: QubitDesignator, target_2: QubitDe
 
 
     :param control: The control qubit.
-    :param target-1: The first target qubit.
-    :param target-2: The second target qubit. The two target states are swapped if the control is
+    :param target_1: The first target qubit.
+    :param target_2: The second target qubit. The two target states are swapped if the control is
         in the ``|1>`` state.
     """
     qubits = [unpack_qubit(q) for q in (control, target_1, target_2)]
diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index 2548fe6cf..886cae94d 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -44,7 +44,7 @@ class Qubit(QuilAtom):
     """
     Representation of a qubit.
 
-    :param int index: Index of the qubit.
+    :param index: Index of the qubit.
     """
 
     def __init__(self, index: int):
@@ -164,7 +164,7 @@ class Label(QuilAtom):
     """
     Representation of a label.
 
-    :param string label_name: The label name.
+    :param label_name: The label name.
     """
 
     def __init__(self, label_name: str):
@@ -320,10 +320,9 @@ def substitute(expr: ExpressionOrValue, d: ParameterSubstitutionsMap) -> Express
     Using a dictionary of substitutions ``d`` try and explicitly evaluate as much of ``expr`` as
     possible.
 
-    :param Expression expr: The expression whose parameters are substituted.
-    :param Mapping[Parameter,Union[int,float]] d: Numerical substitutions for parameters.
+    :param expr: The expression whose parameters are substituted.
+    :param d: Numerical substitutions for parameters.
     :return: A partially simplified Expression or a number.
-    :rtype: Union[Expression,int,float]
     """
     if isinstance(expr, Expression):
         return expr._substitute(d)
@@ -335,10 +334,9 @@ def substitute_array(a: Union[Sequence[Expression], np.array],
     """
     Apply ``substitute`` to all elements of an array ``a`` and return the resulting array.
 
-    :param Union[np.array,Sequence[Expression]] a: The expression array to substitute.
-    :param Mapping[Parameter,Union[int,float]] d: Numerical substitutions for parameters.
+    :param a: The expression array to substitute.
+    :param d: Numerical substitutions for parameters.
     :return: An array of partially substituted Expressions or numbers.
-    :rtype: np.array
     """
     a = np.asarray(a, order="C")
     return np.array([substitute(v, d) for v in a.flat]).reshape(a.shape)
@@ -509,9 +507,8 @@ def _expression_to_string(expression: ExpressionOrValue) -> str:
     Recursively converts an expression to a string taking into account precedence and associativity for placing
     parenthesis
 
-    :param Expression expression: expression involving parameters
+    :param expression: expression involving parameters
     :return: string such as '%x*(%y-4)'
-    :rtype: str
     """
     if isinstance(expression, BinaryExp):
         left = _expression_to_string(expression.op1)
@@ -547,9 +544,8 @@ def _contained_parameters(expression: ExpressionOrValue) -> Set[Parameter]:
     """
     Determine which parameters are contained in this expression.
 
-    :param Expression expression: expression involving parameters
+    :param expression: expression involving parameters
     :return: set of parameters contained in this expression
-    :rtype: set
     """
     if isinstance(expression, BinaryExp):
         return _contained_parameters(expression.op1) | _contained_parameters(expression.op2)
@@ -651,7 +647,7 @@ class Addr(MemoryReference):
     WARNING: Addr has been deprecated. Addr(c) instances are auto-replaced by MemoryReference("ro", c).
              Use MemoryReference instances.
 
-    :param int value: The classical address.
+    :param value: The classical address.
     """
 
     def __init__(self, value: int):
diff --git a/pyquil/quilbase.py b/pyquil/quilbase.py
index aae40960c..f8219d52b 100644
--- a/pyquil/quilbase.py
+++ b/pyquil/quilbase.py
@@ -337,7 +337,7 @@ def format_matrix_element(element: Union[ExpressionOrValue, str]) -> str:
             """
             Formats a parameterized matrix element.
 
-            :param element: {int, float, complex, str} The parameterized element to format.
+            :param element: The parameterized element to format.
             """
             if isinstance(element, (int, float, complex, np.int_)):
                 return format_parameter(element)

From 204a16dc20f085f0b99765e2cd56d6d2da2b608c Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Thu, 10 Oct 2019 11:05:35 -0500
Subject: [PATCH 17/25] Appease mypy by adding a QubitPlaceholder.index
 @property

Sometimes code wants to iterate over instr.qubits, which has type
List[Union[Qubit, QubitPlaceholder]]. Ensure that Qubit and
QubitPlaceholder have matching interfaces to prevent mypy
warnings. Previously, code like [q.index for q in instr.qubits] would
cause mypy to complain because q might be a QubitPlaceholder, which
did not have an index attribute.
---
 pyquil/quilatom.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index 886cae94d..5f4d70bf2 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -16,7 +16,8 @@
 import numpy as np
 from warnings import warn
 from fractions import Fraction
-from typing import Any, Callable, ClassVar, List, Mapping, Optional, Set, Sequence, Tuple, Union
+from typing import (Any, Callable, ClassVar, List, Mapping, NoReturn, Optional, Set, Sequence,
+                    Tuple, Union)
 
 
 class QuilAtom(object):
@@ -72,6 +73,10 @@ class QubitPlaceholder(QuilAtom):
     def out(self) -> str:
         raise RuntimeError("Qubit {} has not been assigned an index".format(self))
 
+    @property
+    def index(self) -> NoReturn:
+        raise RuntimeError("Qubit {} has not been assigned an index".format(self))
+
     def __str__(self) -> str:
         return "q{}".format(id(self))
 

From 8e930b457db09873ebc6d45b5d2b68dd1a5bf1ce Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Thu, 10 Oct 2019 11:51:39 -0500
Subject: [PATCH 18/25] Ensure that right operand of OR is a MemoryReference

Also, restrict types of classical instr constructors in quilbase to
not allow MemoryReferenceDesignator. Desginators are only accepted in
the high-level interfaces found in the gates module.
---
 pyquil/_parser/PyQuilListener.py |  6 +++++-
 pyquil/gates.py                  |  4 ++--
 pyquil/quilatom.py               |  1 +
 pyquil/quilbase.py               | 14 +++++++-------
 4 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/pyquil/_parser/PyQuilListener.py b/pyquil/_parser/PyQuilListener.py
index a492786fe..123ad7f76 100644
--- a/pyquil/_parser/PyQuilListener.py
+++ b/pyquil/_parser/PyQuilListener.py
@@ -279,7 +279,11 @@ def exitLogicalBinaryOp(self, ctx):
         if ctx.AND():
             self.result.append(ClassicalAnd(left, right))
         elif ctx.OR():
-            self.result.append(ClassicalOr(left, right))
+            if isinstance(right, MemoryReference):
+                self.result.append(ClassicalOr(left, right))
+            else:
+                raise RuntimeError("Right operand of deprecated OR instruction must be a"
+                                   f" MemoryReference, but found '{right}'")
         elif ctx.IOR():
             self.result.append(ClassicalInclusiveOr(left, right))
         elif ctx.XOR():
diff --git a/pyquil/gates.py b/pyquil/gates.py
index 6e043e831..5a70ea6a1 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -612,7 +612,7 @@ def IOR(classical_reg1: MemoryReferenceDesignator,
 
     :param classical_reg1: The first classical register, which gets modified.
     :param classical_reg2: The second classical register or immediate value.
-    :return: A ClassicalOr instance.
+    :return: A ClassicalInclusiveOr instance.
     """
     left, right = unpack_reg_val_pair(classical_reg1, classical_reg2)
     return ClassicalInclusiveOr(left, right)
@@ -625,7 +625,7 @@ def XOR(classical_reg1: MemoryReferenceDesignator,
 
     :param classical_reg1: The first classical register, which gets modified.
     :param classical_reg2: The second classical register or immediate value.
-    :return: A ClassicalOr instance.
+    :return: A ClassicalExclusiveOr instance.
     """
     left, right = unpack_reg_val_pair(classical_reg1, classical_reg2)
     return ClassicalExclusiveOr(left, right)
diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index 5f4d70bf2..51dcaa710 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -137,6 +137,7 @@ def unpack_qubit(qubit: QubitDesignator) -> QubitOrPlaceholder:
 MemoryReferenceDesignator = Union['MemoryReference', Tuple[str, int], List[Any], str]
 MRefDesignatorOrImmediateInt = Union[MemoryReferenceDesignator, int]
 MRefDesignatorOrImmediateValue = Union[MemoryReferenceDesignator, int, float]
+MRefOrImmediateInt = Union['MemoryReference', int]
 MRefOrImmediateValue = Union['MemoryReference', int, float]
 
 
diff --git a/pyquil/quilbase.py b/pyquil/quilbase.py
index f8219d52b..04d5fc95c 100644
--- a/pyquil/quilbase.py
+++ b/pyquil/quilbase.py
@@ -23,8 +23,8 @@
 from warnings import warn
 
 from pyquil.quilatom import (Expression, ExpressionOrValue, Label, LabelPlaceholder,
-                             LabelOrPlaceholder, MemoryReference, MRefDesignatorOrImmediateInt,
-                             MRefDesignatorOrImmediateValue, Parameter, ParameterDesignator, Qubit,
+                             LabelOrPlaceholder, MemoryReference, MRefOrImmediateInt,
+                             MRefOrImmediateValue, Parameter, ParameterDesignator, Qubit,
                              QubitDesignator, QubitOrPlaceholder, QubitPlaceholder,
                              _contained_parameters, format_parameter, unpack_qubit)
 
@@ -536,7 +536,7 @@ class LogicalBinaryOp(AbstractInstruction):
     """
     op: ClassVar[str]
 
-    def __init__(self, left: MemoryReference, right: MRefDesignatorOrImmediateInt):
+    def __init__(self, left: MemoryReference, right: MRefOrImmediateInt):
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference) and not isinstance(right, int):
@@ -595,7 +595,7 @@ class ArithmeticBinaryOp(AbstractInstruction):
     """
     op: ClassVar[str]
 
-    def __init__(self, left: MemoryReference, right: MRefDesignatorOrImmediateValue):
+    def __init__(self, left: MemoryReference, right: MRefOrImmediateValue):
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference) and not isinstance(right, int) and not isinstance(right, float):
@@ -645,7 +645,7 @@ class ClassicalMove(AbstractInstruction):
     """
     op = "MOVE"
 
-    def __init__(self, left: MemoryReference, right: MRefDesignatorOrImmediateValue):
+    def __init__(self, left: MemoryReference, right: MRefOrImmediateValue):
         if not isinstance(left, MemoryReference):
             raise TypeError("Left operand of MOVE should be an MemoryReference.  "
                             "Note that the order of the operands in pyQuil 2.0 has reversed from "
@@ -745,7 +745,7 @@ class ClassicalStore(AbstractInstruction):
 
     op = "STORE"
 
-    def __init__(self, target: str, left: MemoryReference, right: MRefDesignatorOrImmediateValue):
+    def __init__(self, target: str, left: MemoryReference, right: MRefOrImmediateValue):
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not (isinstance(right, MemoryReference) or isinstance(right, int)
@@ -766,7 +766,7 @@ class ClassicalComparison(AbstractInstruction):
     op: ClassVar[str]
 
     def __init__(self, target: MemoryReference, left: MemoryReference,
-                 right: MRefDesignatorOrImmediateValue):
+                 right: MRefOrImmediateValue):
         if not isinstance(target, MemoryReference):
             raise TypeError("target operand should be an MemoryReference")
         if not isinstance(left, MemoryReference):

From 3ca6df38212d2e5ea93ccda71489dd7d58e817b3 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Thu, 10 Oct 2019 12:59:06 -0500
Subject: [PATCH 19/25] Add type hint for previously untyped quil_cis

---
 pyquil/quilatom.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index 51dcaa710..597e05341 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -17,7 +17,7 @@
 from warnings import warn
 from fractions import Fraction
 from typing import (Any, Callable, ClassVar, List, Mapping, NoReturn, Optional, Set, Sequence,
-                    Tuple, Union)
+                    Tuple, Union, cast)
 
 
 class QuilAtom(object):
@@ -414,7 +414,11 @@ def quil_exp(expression: ExpressionOrValue) -> Function:
 
 
 def quil_cis(expression: ExpressionOrValue) -> Function:
-    return Function('CIS', expression, lambda x: np.exp(1j * x))  # type: ignore
+    def _cis(x: ExpressionValue) -> complex:
+        # numpy doesn't ship with type stubs, so mypy assumes anything coming from numpy has type
+        # Any, hence we need to cast the return type to complex here to satisfy the type checker.
+        return cast(complex, np.exp(1j * x))
+    return Function('CIS', expression, _cis)
 
 
 class BinaryExp(Expression):

From 1f08a54a32ac96877c3916712654054dee1da4a3 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Thu, 10 Oct 2019 13:38:44 -0500
Subject: [PATCH 20/25] Update CHANGELOG blurb to include quilbase module

---
 CHANGELOG.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7f080c5c8..cf4559aa0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -78,7 +78,8 @@ Changelog
     the `--runslow` option is specified for `pytest` (@kilimanjaro, gh-1001).
 -   `PauliSum` objects can now be constructed from strings via `from_compact_str()`
     and `PauliTerm.from_compact_str()` supports multi-qubit strings (@jlbosse, gh-984).
--   Type hints have been added to `pyquil.gates` and `pyquil.quilatom` modules (@appleby gh-999).
+-   Type hints have been added to the `pyquil.gates`, `pyquil.quilatom`, and `pyquil.quilbase`
+    modules (@appleby gh-999).
 
 ### Bugfixes
 

From 21042ff51e8e32d13f94ef0bcbbb51b59a0a5fca Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Wed, 30 Oct 2019 16:16:22 -0600
Subject: [PATCH 21/25] Reduce type aliases and standardize on "Designator"
 suffix

---
 pyquil/gates.py    | 44 ++++++++++++-----------
 pyquil/quilatom.py | 90 ++++++++++++++++++++++------------------------
 pyquil/quilbase.py | 41 +++++++++++----------
 3 files changed, 85 insertions(+), 90 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index 5a70ea6a1..2b4eef254 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -17,9 +17,8 @@
 from typing import Any, Callable, Mapping, Optional, Tuple, Union, overload
 
 from pyquil.quilatom import (Addr, Expression, MemoryReference, MemoryReferenceDesignator,
-                             MRefDesignatorOrImmediateInt, MRefDesignatorOrImmediateValue,
-                             MRefOrImmediateValue, Parameter, ParameterDesignator, Qubit,
-                             QubitDesignator, QubitPlaceholder, unpack_classical_reg, unpack_qubit)
+                             Parameter, ParameterDesignator, Qubit, QubitDesignator,
+                             QubitPlaceholder, unpack_classical_reg, unpack_qubit)
 from pyquil.quilbase import (AbstractInstruction, Gate, Halt, Reset, ResetQubit, Measurement, Nop,
                              Wait,
                              ClassicalNeg, ClassicalNot,
@@ -60,8 +59,8 @@ def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
 
 
 def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
-                        classical_reg2: MRefDesignatorOrImmediateValue) \
-                        -> Tuple[MemoryReference, MRefOrImmediateValue]:
+                        classical_reg2: Union[MemoryReferenceDesignator, int, float]) \
+                        -> Tuple[MemoryReference, Union[MemoryReference, int, float]]:
     """
     Helper function for typechecking / type-coercing arguments to constructors for binary classical operators.
 
@@ -77,8 +76,8 @@ def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
 
 def prepare_ternary_operands(classical_reg1: MemoryReferenceDesignator,
                              classical_reg2: MemoryReferenceDesignator,
-                             classical_reg3: MRefDesignatorOrImmediateValue) \
-                             -> Tuple[MemoryReference, MemoryReference, MRefOrImmediateValue]:
+                             classical_reg3: Union[MemoryReferenceDesignator, int, float]) \
+                             -> Tuple[MemoryReference, MemoryReference, Union[MemoryReference, int, float]]:
     """
     Helper function for typechecking / type-coercing arguments to constructors for ternary classical operators.
 
@@ -576,7 +575,8 @@ def NOT(classical_reg: MemoryReferenceDesignator) -> ClassicalNot:
 
 
 def AND(classical_reg1: MemoryReferenceDesignator,
-        classical_reg2: MRefDesignatorOrImmediateInt) -> ClassicalAnd:
+        classical_reg2: Union[MemoryReferenceDesignator, int]
+) -> ClassicalAnd:
     """
     Produce an AND instruction.
 
@@ -606,7 +606,8 @@ def OR(classical_reg1: MemoryReferenceDesignator,
 
 
 def IOR(classical_reg1: MemoryReferenceDesignator,
-        classical_reg2: MRefDesignatorOrImmediateInt) -> ClassicalInclusiveOr:
+        classical_reg2: Union[MemoryReferenceDesignator, int]
+) -> ClassicalInclusiveOr:
     """
     Produce an inclusive OR instruction.
 
@@ -619,7 +620,8 @@ def IOR(classical_reg1: MemoryReferenceDesignator,
 
 
 def XOR(classical_reg1: MemoryReferenceDesignator,
-        classical_reg2: MRefDesignatorOrImmediateInt) -> ClassicalExclusiveOr:
+        classical_reg2: Union[MemoryReferenceDesignator, int]
+) -> ClassicalExclusiveOr:
     """
     Produce an exclusive OR instruction.
 
@@ -632,7 +634,7 @@ def XOR(classical_reg1: MemoryReferenceDesignator,
 
 
 def MOVE(classical_reg1: MemoryReferenceDesignator,
-         classical_reg2: MRefDesignatorOrImmediateValue) -> ClassicalMove:
+         classical_reg2: Union[MemoryReferenceDesignator, int, float]) -> ClassicalMove:
     """
     Produce a MOVE instruction.
 
@@ -674,7 +676,7 @@ def LOAD(target_reg: MemoryReferenceDesignator,
 
 def STORE(region_name: str,
           offset_reg: MemoryReferenceDesignator,
-          source: MRefDesignatorOrImmediateValue) -> ClassicalStore:
+          source: Union[MemoryReferenceDesignator, int, float]) -> ClassicalStore:
     """
     Produce a STORE instruction.
 
@@ -702,7 +704,7 @@ def CONVERT(classical_reg1: MemoryReferenceDesignator,
 
 
 def ADD(classical_reg: MemoryReferenceDesignator,
-        right: MRefDesignatorOrImmediateValue) -> ClassicalAdd:
+        right: Union[MemoryReferenceDesignator, int, float]) -> ClassicalAdd:
     """
     Produce an ADD instruction.
 
@@ -715,7 +717,7 @@ def ADD(classical_reg: MemoryReferenceDesignator,
 
 
 def SUB(classical_reg: MemoryReferenceDesignator,
-        right: MRefDesignatorOrImmediateValue) -> ClassicalSub:
+        right: Union[MemoryReferenceDesignator, int, float]) -> ClassicalSub:
     """
     Produce a SUB instruction.
 
@@ -728,7 +730,7 @@ def SUB(classical_reg: MemoryReferenceDesignator,
 
 
 def MUL(classical_reg: MemoryReferenceDesignator,
-        right: MRefDesignatorOrImmediateValue) -> ClassicalMul:
+        right: Union[MemoryReferenceDesignator, int, float]) -> ClassicalMul:
     """
     Produce a MUL instruction.
 
@@ -741,7 +743,7 @@ def MUL(classical_reg: MemoryReferenceDesignator,
 
 
 def DIV(classical_reg: MemoryReferenceDesignator,
-        right: MRefDesignatorOrImmediateValue) -> ClassicalDiv:
+        right: Union[MemoryReferenceDesignator, int, float]) -> ClassicalDiv:
     """
     Produce an DIV instruction.
 
@@ -755,7 +757,7 @@ def DIV(classical_reg: MemoryReferenceDesignator,
 
 def EQ(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MRefDesignatorOrImmediateValue) -> ClassicalEqual:
+       classical_reg3: Union[MemoryReferenceDesignator, int, float]) -> ClassicalEqual:
     """
     Produce an EQ instruction.
 
@@ -773,7 +775,7 @@ def EQ(classical_reg1: MemoryReferenceDesignator,
 
 def LT(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MRefDesignatorOrImmediateValue) -> ClassicalLessThan:
+       classical_reg3: Union[MemoryReferenceDesignator, int, float]) -> ClassicalLessThan:
     """
     Produce an LT instruction.
 
@@ -790,7 +792,7 @@ def LT(classical_reg1: MemoryReferenceDesignator,
 
 def LE(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MRefDesignatorOrImmediateValue) -> ClassicalLessEqual:
+       classical_reg3: Union[MemoryReferenceDesignator, int, float]) -> ClassicalLessEqual:
     """
     Produce an LE instruction.
 
@@ -807,7 +809,7 @@ def LE(classical_reg1: MemoryReferenceDesignator,
 
 def GT(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MRefDesignatorOrImmediateValue) -> ClassicalGreaterThan:
+       classical_reg3: Union[MemoryReferenceDesignator, int, float]) -> ClassicalGreaterThan:
     """
     Produce an GT instruction.
 
@@ -824,7 +826,7 @@ def GT(classical_reg1: MemoryReferenceDesignator,
 
 def GE(classical_reg1: MemoryReferenceDesignator,
        classical_reg2: MemoryReferenceDesignator,
-       classical_reg3: MRefDesignatorOrImmediateValue) -> ClassicalGreaterEqual:
+       classical_reg3: Union[MemoryReferenceDesignator, int, float]) -> ClassicalGreaterEqual:
     """
     Produce an GE instruction.
 
diff --git a/pyquil/quilatom.py b/pyquil/quilatom.py
index 597e05341..acbac8ab6 100644
--- a/pyquil/quilatom.py
+++ b/pyquil/quilatom.py
@@ -109,11 +109,10 @@ def register(cls, n: int) -> List['QubitPlaceholder']:
         return [cls() for _ in range(n)]
 
 
-QubitOrPlaceholder = Union[Qubit, QubitPlaceholder]
 QubitDesignator = Union[Qubit, QubitPlaceholder, int]
 
 
-def unpack_qubit(qubit: QubitDesignator) -> QubitOrPlaceholder:
+def unpack_qubit(qubit: QubitDesignator) -> Union[Qubit, QubitPlaceholder]:
     """
     Get a qubit from an object.
 
@@ -135,10 +134,6 @@ def unpack_qubit(qubit: QubitDesignator) -> QubitOrPlaceholder:
 # constrain the types, and mypy gets confused in unpack_classical_reg, below. Hence, just specify
 # List[Any] here.
 MemoryReferenceDesignator = Union['MemoryReference', Tuple[str, int], List[Any], str]
-MRefDesignatorOrImmediateInt = Union[MemoryReferenceDesignator, int]
-MRefDesignatorOrImmediateValue = Union[MemoryReferenceDesignator, int, float]
-MRefOrImmediateInt = Union['MemoryReference', int]
-MRefOrImmediateValue = Union['MemoryReference', int, float]
 
 
 def unpack_classical_reg(c: MemoryReferenceDesignator) -> 'MemoryReference':
@@ -212,7 +207,6 @@ def __hash__(self) -> int:
         return hash(id(self))
 
 
-LabelOrPlaceholder = Union[Label, LabelPlaceholder]
 ParameterDesignator = Union['Expression', 'MemoryReference', np.int_, int, float, complex]
 
 
@@ -258,8 +252,8 @@ def format_parameter(element: ParameterDesignator) -> str:
     assert False, "Invalid parameter: %r" % element
 
 
-ExpressionValue = Union[int, float, complex]
-ExpressionOrValue = Union['Expression', ExpressionValue]
+ExpressionValueDesignator = Union[int, float, complex]
+ExpressionDesignator = Union['Expression', ExpressionValueDesignator]
 
 
 class Expression(object):
@@ -277,51 +271,51 @@ def __str__(self) -> str:
     def __repr__(self) -> str:
         return str(self.__class__.__name__) + '(' + ','.join(map(repr, self.__dict__.values())) + ')'
 
-    def __add__(self, other: ExpressionOrValue) -> 'Add':
+    def __add__(self, other: ExpressionDesignator) -> 'Add':
         return Add(self, other)
 
-    def __radd__(self, other: ExpressionOrValue) -> 'Add':
+    def __radd__(self, other: ExpressionDesignator) -> 'Add':
         return Add(other, self)
 
-    def __sub__(self, other: ExpressionOrValue) -> 'Sub':
+    def __sub__(self, other: ExpressionDesignator) -> 'Sub':
         return Sub(self, other)
 
-    def __rsub__(self, other: ExpressionOrValue) -> 'Sub':
+    def __rsub__(self, other: ExpressionDesignator) -> 'Sub':
         return Sub(other, self)
 
-    def __mul__(self, other: ExpressionOrValue) -> 'Mul':
+    def __mul__(self, other: ExpressionDesignator) -> 'Mul':
         return Mul(self, other)
 
-    def __rmul__(self, other: ExpressionOrValue) -> 'Mul':
+    def __rmul__(self, other: ExpressionDesignator) -> 'Mul':
         return Mul(other, self)
 
-    def __div__(self, other: ExpressionOrValue) -> 'Div':
+    def __div__(self, other: ExpressionDesignator) -> 'Div':
         return Div(self, other)
 
     __truediv__ = __div__
 
-    def __rdiv__(self, other: ExpressionOrValue) -> 'Div':
+    def __rdiv__(self, other: ExpressionDesignator) -> 'Div':
         return Div(other, self)
 
     __rtruediv__ = __rdiv__
 
-    def __pow__(self, other: ExpressionOrValue) -> 'Pow':
+    def __pow__(self, other: ExpressionDesignator) -> 'Pow':
         return Pow(self, other)
 
-    def __rpow__(self, other: ExpressionOrValue) -> 'Pow':
+    def __rpow__(self, other: ExpressionDesignator) -> 'Pow':
         return Pow(other, self)
 
     def __neg__(self) -> 'Mul':
         return Mul(-1, self)
 
-    def _substitute(self, d: Any) -> 'ExpressionOrValue':
+    def _substitute(self, d: Any) -> ExpressionDesignator:
         return self
 
 
-ParameterSubstitutionsMap = Mapping['Parameter', ExpressionValue]
+ParamSubstitutionsMapDesignator = Mapping['Parameter', ExpressionValueDesignator]
 
 
-def substitute(expr: ExpressionOrValue, d: ParameterSubstitutionsMap) -> ExpressionOrValue:
+def substitute(expr: ExpressionDesignator, d: ParamSubstitutionsMapDesignator) -> ExpressionDesignator:
     """
     Using a dictionary of substitutions ``d`` try and explicitly evaluate as much of ``expr`` as
     possible.
@@ -336,7 +330,7 @@ def substitute(expr: ExpressionOrValue, d: ParameterSubstitutionsMap) -> Express
 
 
 def substitute_array(a: Union[Sequence[Expression], np.array],
-                     d: ParameterSubstitutionsMap) -> np.array:
+                     d: ParamSubstitutionsMapDesignator) -> np.array:
     """
     Apply ``substitute`` to all elements of an array ``a`` and return the resulting array.
 
@@ -359,7 +353,7 @@ def __init__(self, name: str):
     def out(self) -> str:
         return '%' + self.name
 
-    def _substitute(self, d: ParameterSubstitutionsMap) -> Union['Parameter', ExpressionValue]:
+    def _substitute(self, d: ParamSubstitutionsMapDesignator) -> Union['Parameter', ExpressionValueDesignator]:
         return d.get(self, self)
 
     def __str__(self) -> str:
@@ -376,13 +370,13 @@ class Function(Expression):
     """
     Supported functions in Quil are sin, cos, sqrt, exp, and cis
     """
-    def __init__(self, name: str, expression: ExpressionOrValue,
-                 fn: Callable[[ExpressionValue], ExpressionValue]):
+    def __init__(self, name: str, expression: ExpressionDesignator,
+                 fn: Callable[[ExpressionValueDesignator], ExpressionValueDesignator]):
         self.name = name
         self.expression = expression
         self.fn = fn
 
-    def _substitute(self, d: ParameterSubstitutionsMap) -> Union['Function', ExpressionValue]:
+    def _substitute(self, d: ParamSubstitutionsMapDesignator) -> Union['Function', ExpressionValueDesignator]:
         sop = substitute(self.expression, d)
         if isinstance(sop, Expression):
             return Function(self.name, sop, self.fn)
@@ -397,24 +391,24 @@ def __neq__(self, other: 'Function') -> bool:
         return not self.__eq__(other)
 
 
-def quil_sin(expression: ExpressionOrValue) -> Function:
+def quil_sin(expression: ExpressionDesignator) -> Function:
     return Function('SIN', expression, np.sin)
 
 
-def quil_cos(expression: ExpressionOrValue) -> Function:
+def quil_cos(expression: ExpressionDesignator) -> Function:
     return Function('COS', expression, np.cos)
 
 
-def quil_sqrt(expression: ExpressionOrValue) -> Function:
+def quil_sqrt(expression: ExpressionDesignator) -> Function:
     return Function('SQRT', expression, np.sqrt)
 
 
-def quil_exp(expression: ExpressionOrValue) -> Function:
+def quil_exp(expression: ExpressionDesignator) -> Function:
     return Function('EXP', expression, np.exp)
 
 
-def quil_cis(expression: ExpressionOrValue) -> Function:
-    def _cis(x: ExpressionValue) -> complex:
+def quil_cis(expression: ExpressionDesignator) -> Function:
+    def _cis(x: ExpressionValueDesignator) -> complex:
         # numpy doesn't ship with type stubs, so mypy assumes anything coming from numpy has type
         # Any, hence we need to cast the return type to complex here to satisfy the type checker.
         return cast(complex, np.exp(1j * x))
@@ -427,14 +421,14 @@ class BinaryExp(Expression):
     associates: ClassVar[str]
 
     @staticmethod
-    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['BinaryExp', ExpressionValue]:
+    def fn(a: ExpressionDesignator, b: ExpressionDesignator) -> Union['BinaryExp', ExpressionValueDesignator]:
         raise NotImplementedError
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
+    def __init__(self, op1: ExpressionDesignator, op2: ExpressionDesignator):
         self.op1 = op1
         self.op2 = op2
 
-    def _substitute(self, d: ParameterSubstitutionsMap) -> Union['BinaryExp', ExpressionValue]:
+    def _substitute(self, d: ParamSubstitutionsMapDesignator) -> Union['BinaryExp', ExpressionValueDesignator]:
         sop1, sop2 = substitute(self.op1, d), substitute(self.op2, d)
         return self.fn(sop1, sop2)
 
@@ -453,10 +447,10 @@ class Add(BinaryExp):
     associates = 'both'
 
     @staticmethod
-    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Add', ExpressionValue]:
+    def fn(a: ExpressionDesignator, b: ExpressionDesignator) -> Union['Add', ExpressionValueDesignator]:
         return a + b
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
+    def __init__(self, op1: ExpressionDesignator, op2: ExpressionDesignator):
         super(Add, self).__init__(op1, op2)
 
 
@@ -466,10 +460,10 @@ class Sub(BinaryExp):
     associates = 'left'
 
     @staticmethod
-    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Sub', ExpressionValue]:
+    def fn(a: ExpressionDesignator, b: ExpressionDesignator) -> Union['Sub', ExpressionValueDesignator]:
         return a - b
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
+    def __init__(self, op1: ExpressionDesignator, op2: ExpressionDesignator):
         super(Sub, self).__init__(op1, op2)
 
 
@@ -479,10 +473,10 @@ class Mul(BinaryExp):
     associates = 'both'
 
     @staticmethod
-    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Mul', ExpressionValue]:
+    def fn(a: ExpressionDesignator, b: ExpressionDesignator) -> Union['Mul', ExpressionValueDesignator]:
         return a * b
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
+    def __init__(self, op1: ExpressionDesignator, op2: ExpressionDesignator):
         super(Mul, self).__init__(op1, op2)
 
 
@@ -492,10 +486,10 @@ class Div(BinaryExp):
     associates = 'left'
 
     @staticmethod
-    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Div', ExpressionValue]:
+    def fn(a: ExpressionDesignator, b: ExpressionDesignator) -> Union['Div', ExpressionValueDesignator]:
         return a / b
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
+    def __init__(self, op1: ExpressionDesignator, op2: ExpressionDesignator):
         super(Div, self).__init__(op1, op2)
 
 
@@ -505,14 +499,14 @@ class Pow(BinaryExp):
     associates = 'right'
 
     @staticmethod
-    def fn(a: ExpressionOrValue, b: ExpressionOrValue) -> Union['Pow', ExpressionValue]:
+    def fn(a: ExpressionDesignator, b: ExpressionDesignator) -> Union['Pow', ExpressionValueDesignator]:
         return a ** b
 
-    def __init__(self, op1: ExpressionOrValue, op2: ExpressionOrValue):
+    def __init__(self, op1: ExpressionDesignator, op2: ExpressionDesignator):
         super(Pow, self).__init__(op1, op2)
 
 
-def _expression_to_string(expression: ExpressionOrValue) -> str:
+def _expression_to_string(expression: ExpressionDesignator) -> str:
     """
     Recursively converts an expression to a string taking into account precedence and associativity for placing
     parenthesis
@@ -550,7 +544,7 @@ def _expression_to_string(expression: ExpressionOrValue) -> str:
         return format_parameter(expression)
 
 
-def _contained_parameters(expression: ExpressionOrValue) -> Set[Parameter]:
+def _contained_parameters(expression: ExpressionDesignator) -> Set[Parameter]:
     """
     Determine which parameters are contained in this expression.
 
diff --git a/pyquil/quilbase.py b/pyquil/quilbase.py
index 04d5fc95c..7ad90d421 100644
--- a/pyquil/quilbase.py
+++ b/pyquil/quilbase.py
@@ -22,11 +22,10 @@
                     Union)
 from warnings import warn
 
-from pyquil.quilatom import (Expression, ExpressionOrValue, Label, LabelPlaceholder,
-                             LabelOrPlaceholder, MemoryReference, MRefOrImmediateInt,
-                             MRefOrImmediateValue, Parameter, ParameterDesignator, Qubit,
-                             QubitDesignator, QubitOrPlaceholder, QubitPlaceholder,
-                             _contained_parameters, format_parameter, unpack_qubit)
+from pyquil.quilatom import (Expression, ExpressionDesignator, Label, LabelPlaceholder,
+                             MemoryReference, Parameter, ParameterDesignator, Qubit,
+                             QubitDesignator, QubitPlaceholder, _contained_parameters,
+                             format_parameter, unpack_qubit)
 
 
 class AbstractInstruction(object):
@@ -65,23 +64,23 @@ def __hash__(self) -> int:
 ]
 
 
-def _extract_qubit_index(qubit: QubitOrPlaceholder, index: bool = True) -> QubitDesignator:
+def _extract_qubit_index(qubit: Union[Qubit, QubitPlaceholder], index: bool = True) -> QubitDesignator:
     if (not index) or isinstance(qubit, QubitPlaceholder):
         return qubit
     return qubit.index
 
 
-def _format_qubit_str(qubit: QubitOrPlaceholder) -> str:
+def _format_qubit_str(qubit: Union[Qubit, QubitPlaceholder]) -> str:
     if isinstance(qubit, QubitPlaceholder):
         return "{%s}" % str(qubit)
     return str(qubit)
 
 
-def _format_qubits_str(qubits: Iterable[QubitOrPlaceholder]) -> str:
+def _format_qubits_str(qubits: Iterable[Union[Qubit, QubitPlaceholder]]) -> str:
     return " ".join([_format_qubit_str(qubit) for qubit in qubits])
 
 
-def _format_qubits_out(qubits: Iterable[QubitOrPlaceholder]) -> str:
+def _format_qubits_out(qubits: Iterable[Union[Qubit, QubitPlaceholder]]) -> str:
     return " ".join([qubit.out() for qubit in qubits])
 
 
@@ -95,7 +94,7 @@ class Gate(AbstractInstruction):
     """
 
     def __init__(self, name: str, params: Iterable[ParameterDesignator],
-                 qubits: Iterable[QubitOrPlaceholder]):
+                 qubits: Iterable[Union[Qubit, QubitPlaceholder]]):
         if not isinstance(name, str):
             raise TypeError("Gate name must be a string")
 
@@ -232,7 +231,7 @@ class Measurement(AbstractInstruction):
     This is the pyQuil object for a Quil measurement instruction.
     """
 
-    def __init__(self, qubit: QubitOrPlaceholder, classical_reg: Optional[MemoryReference]):
+    def __init__(self, qubit: Union[Qubit, QubitPlaceholder], classical_reg: Optional[MemoryReference]):
         if not isinstance(qubit, (Qubit, QubitPlaceholder)):
             raise TypeError("qubit should be a Qubit")
         if classical_reg is not None and not isinstance(classical_reg, MemoryReference):
@@ -262,7 +261,7 @@ class ResetQubit(AbstractInstruction):
     This is the pyQuil object for a Quil targeted reset instruction.
     """
 
-    def __init__(self, qubit: QubitOrPlaceholder):
+    def __init__(self, qubit: Union[Qubit, QubitPlaceholder]):
         if not isinstance(qubit, (Qubit, QubitPlaceholder)):
             raise TypeError("qubit should be a Qubit")
         self.qubit = qubit
@@ -333,7 +332,7 @@ def out(self) -> str:
 
         :returns: String representation of a gate
         """
-        def format_matrix_element(element: Union[ExpressionOrValue, str]) -> str:
+        def format_matrix_element(element: Union[ExpressionDesignator, str]) -> str:
             """
             Formats a parameterized matrix element.
 
@@ -419,7 +418,7 @@ class JumpTarget(AbstractInstruction):
     Representation of a target that can be jumped to.
     """
 
-    def __init__(self, label: LabelOrPlaceholder):
+    def __init__(self, label: Union[Label, LabelPlaceholder]):
         if not isinstance(label, (Label, LabelPlaceholder)):
             raise TypeError("label must be a Label")
         self.label = label
@@ -437,7 +436,7 @@ class JumpConditional(AbstractInstruction):
     """
     op: ClassVar[str]
 
-    def __init__(self, target: LabelOrPlaceholder, condition: MemoryReference):
+    def __init__(self, target: Union[Label, LabelPlaceholder], condition: MemoryReference):
         if not isinstance(target, (Label, LabelPlaceholder)):
             raise TypeError("target should be a Label")
         if not isinstance(condition, MemoryReference):
@@ -536,7 +535,7 @@ class LogicalBinaryOp(AbstractInstruction):
     """
     op: ClassVar[str]
 
-    def __init__(self, left: MemoryReference, right: MRefOrImmediateInt):
+    def __init__(self, left: MemoryReference, right: Union[MemoryReference, int]):
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference) and not isinstance(right, int):
@@ -595,7 +594,7 @@ class ArithmeticBinaryOp(AbstractInstruction):
     """
     op: ClassVar[str]
 
-    def __init__(self, left: MemoryReference, right: MRefOrImmediateValue):
+    def __init__(self, left: MemoryReference, right: Union[MemoryReference, int, float]):
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not isinstance(right, MemoryReference) and not isinstance(right, int) and not isinstance(right, float):
@@ -645,7 +644,7 @@ class ClassicalMove(AbstractInstruction):
     """
     op = "MOVE"
 
-    def __init__(self, left: MemoryReference, right: MRefOrImmediateValue):
+    def __init__(self, left: MemoryReference, right: Union[MemoryReference, int, float]):
         if not isinstance(left, MemoryReference):
             raise TypeError("Left operand of MOVE should be an MemoryReference.  "
                             "Note that the order of the operands in pyQuil 2.0 has reversed from "
@@ -745,7 +744,7 @@ class ClassicalStore(AbstractInstruction):
 
     op = "STORE"
 
-    def __init__(self, target: str, left: MemoryReference, right: MRefOrImmediateValue):
+    def __init__(self, target: str, left: MemoryReference, right: Union[MemoryReference, int, float]):
         if not isinstance(left, MemoryReference):
             raise TypeError("left operand should be an MemoryReference")
         if not (isinstance(right, MemoryReference) or isinstance(right, int)
@@ -766,7 +765,7 @@ class ClassicalComparison(AbstractInstruction):
     op: ClassVar[str]
 
     def __init__(self, target: MemoryReference, left: MemoryReference,
-                 right: MRefOrImmediateValue):
+                 right: Union[MemoryReference, int, float]):
         if not isinstance(target, MemoryReference):
             raise TypeError("target operand should be an MemoryReference")
         if not isinstance(left, MemoryReference):
@@ -827,7 +826,7 @@ class Jump(AbstractInstruction):
     Representation of an unconditional jump instruction (JUMP).
     """
 
-    def __init__(self, target: LabelOrPlaceholder):
+    def __init__(self, target: Union[Label, LabelPlaceholder]):
         if not isinstance(target, (Label, LabelPlaceholder)):
             raise TypeError("target should be a Label")
         self.target = target

From ea86963726f3b108cf1ac7b10570474c71af8260 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Wed, 30 Oct 2019 16:44:28 -0600
Subject: [PATCH 22/25] Nix unpack_reg_val_pair overloads and replace with
 isinstance asserts

These asserts are required to help mypy deduce that the types are
sufficiently constrained.
---
 pyquil/gates.py | 31 +++----------------------------
 1 file changed, 3 insertions(+), 28 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index 2b4eef254..a3593c497 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -30,34 +30,6 @@
                              ClassicalAdd, ClassicalSub, ClassicalMul, ClassicalDiv)
 
 
-# These @overloads are needed to help mypy with type inference. Note that the order of the overloads
-# is important! According to the mypy docs, overloads should proceed from most-specific ->
-# least-specific type, and should appear in the same order as the isinstance checks in the
-# implementation body.
-#
-# https://mypy.readthedocs.io/en/latest/more_types.html#function-overloading
-# https://github.com/python/mypy/issues/1693
-@overload
-def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
-                        classical_reg2: int) \
-                        -> Tuple[MemoryReference, int]:
-    ...
-
-
-@overload
-def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
-                        classical_reg2: float) \
-                        -> Tuple[MemoryReference, float]:
-    ...
-
-
-@overload
-def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
-                        classical_reg2: MemoryReferenceDesignator) \
-                        -> Tuple[MemoryReference, MemoryReference]:
-    ...
-
-
 def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
                         classical_reg2: Union[MemoryReferenceDesignator, int, float]) \
                         -> Tuple[MemoryReference, Union[MemoryReference, int, float]]:
@@ -587,6 +559,7 @@ def AND(classical_reg1: MemoryReferenceDesignator,
     :return: A ClassicalAnd instance.
     """
     left, right = unpack_reg_val_pair(classical_reg1, classical_reg2)
+    assert isinstance(right, (MemoryReference, int))  # placate mypy
     return ClassicalAnd(left, right)
 
 
@@ -616,6 +589,7 @@ def IOR(classical_reg1: MemoryReferenceDesignator,
     :return: A ClassicalInclusiveOr instance.
     """
     left, right = unpack_reg_val_pair(classical_reg1, classical_reg2)
+    assert isinstance(right, (MemoryReference, int))  # placate mypy
     return ClassicalInclusiveOr(left, right)
 
 
@@ -630,6 +604,7 @@ def XOR(classical_reg1: MemoryReferenceDesignator,
     :return: A ClassicalExclusiveOr instance.
     """
     left, right = unpack_reg_val_pair(classical_reg1, classical_reg2)
+    assert isinstance(right, (MemoryReference, int))  # placate mypy
     return ClassicalExclusiveOr(left, right)
 
 

From c2a2b98ba97d94302a78182e1bc55bd52bd23c1f Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Wed, 30 Oct 2019 16:54:21 -0600
Subject: [PATCH 23/25] Rename Executable type alias to ExecutableDesignator

And use it as the return type for QuantumComputer.compile.
---
 pyquil/api/_quantum_computer.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pyquil/api/_quantum_computer.py b/pyquil/api/_quantum_computer.py
index af122375c..5cc903b89 100644
--- a/pyquil/api/_quantum_computer.py
+++ b/pyquil/api/_quantum_computer.py
@@ -42,7 +42,7 @@
 from pyquil.quil import Program, validate_supported_quil
 
 
-Executable = Union[BinaryExecutableResponse, PyQuilExecutableResponse]
+ExecutableDesignator = Union[BinaryExecutableResponse, PyQuilExecutableResponse]
 
 
 class QuantumComputer:
@@ -107,7 +107,7 @@ def get_isa(self, oneq_type: str = 'Xhalves',
         return self.device.get_isa(oneq_type=oneq_type, twoq_type=twoq_type)
 
     @_record_call
-    def run(self, executable: Executable,
+    def run(self, executable: ExecutableDesignator,
             memory_map: Dict[str, List[Union[int, float]]] = None) -> np.ndarray:
         """
         Run a quil executable. If the executable contains declared parameters, then a memory
@@ -261,7 +261,7 @@ def compile(
             protoquil_positional: bool = None,
             *,
             protoquil: bool = None,
-    ) -> Union[BinaryExecutableResponse, PyQuilExecutableResponse]:
+    ) -> ExecutableDesignator:
         """
         A high-level interface to program compilation.
 

From 380bec22387ab6e2fd880529179888a94c56b194 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Wed, 30 Oct 2019 17:00:43 -0600
Subject: [PATCH 24/25] Prefer dangling close paren for overlong function
 signatures

---
 pyquil/gates.py | 25 ++++++++++++-------------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/pyquil/gates.py b/pyquil/gates.py
index a3593c497..8bf5cd07b 100644
--- a/pyquil/gates.py
+++ b/pyquil/gates.py
@@ -30,9 +30,10 @@
                              ClassicalAdd, ClassicalSub, ClassicalMul, ClassicalDiv)
 
 
-def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
-                        classical_reg2: Union[MemoryReferenceDesignator, int, float]) \
-                        -> Tuple[MemoryReference, Union[MemoryReference, int, float]]:
+def unpack_reg_val_pair(
+        classical_reg1: MemoryReferenceDesignator,
+        classical_reg2: Union[MemoryReferenceDesignator, int, float]
+) -> Tuple[MemoryReference, Union[MemoryReference, int, float]]:
     """
     Helper function for typechecking / type-coercing arguments to constructors for binary classical operators.
 
@@ -46,10 +47,11 @@ def unpack_reg_val_pair(classical_reg1: MemoryReferenceDesignator,
     return left, unpack_classical_reg(classical_reg2)
 
 
-def prepare_ternary_operands(classical_reg1: MemoryReferenceDesignator,
-                             classical_reg2: MemoryReferenceDesignator,
-                             classical_reg3: Union[MemoryReferenceDesignator, int, float]) \
-                             -> Tuple[MemoryReference, MemoryReference, Union[MemoryReference, int, float]]:
+def prepare_ternary_operands(
+        classical_reg1: MemoryReferenceDesignator,
+        classical_reg2: MemoryReferenceDesignator,
+        classical_reg3: Union[MemoryReferenceDesignator, int, float]
+) -> Tuple[MemoryReference, MemoryReference, Union[MemoryReference, int, float]]:
     """
     Helper function for typechecking / type-coercing arguments to constructors for ternary classical operators.
 
@@ -547,8 +549,7 @@ def NOT(classical_reg: MemoryReferenceDesignator) -> ClassicalNot:
 
 
 def AND(classical_reg1: MemoryReferenceDesignator,
-        classical_reg2: Union[MemoryReferenceDesignator, int]
-) -> ClassicalAnd:
+        classical_reg2: Union[MemoryReferenceDesignator, int]) -> ClassicalAnd:
     """
     Produce an AND instruction.
 
@@ -579,8 +580,7 @@ def OR(classical_reg1: MemoryReferenceDesignator,
 
 
 def IOR(classical_reg1: MemoryReferenceDesignator,
-        classical_reg2: Union[MemoryReferenceDesignator, int]
-) -> ClassicalInclusiveOr:
+        classical_reg2: Union[MemoryReferenceDesignator, int]) -> ClassicalInclusiveOr:
     """
     Produce an inclusive OR instruction.
 
@@ -594,8 +594,7 @@ def IOR(classical_reg1: MemoryReferenceDesignator,
 
 
 def XOR(classical_reg1: MemoryReferenceDesignator,
-        classical_reg2: Union[MemoryReferenceDesignator, int]
-) -> ClassicalExclusiveOr:
+        classical_reg2: Union[MemoryReferenceDesignator, int]) -> ClassicalExclusiveOr:
     """
     Produce an exclusive OR instruction.
 

From 4072509910235514c12e90764c17b253ce49a4d0 Mon Sep 17 00:00:00 2001
From: Mike Appleby <86076+appleby@users.noreply.github.com>
Date: Wed, 30 Oct 2019 17:34:51 -0600
Subject: [PATCH 25/25] Replace references to DeclareOffsets type alias with
 Union

---
 pyquil/quilbase.py | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/pyquil/quilbase.py b/pyquil/quilbase.py
index 7ad90d421..5feddde36 100644
--- a/pyquil/quilbase.py
+++ b/pyquil/quilbase.py
@@ -879,9 +879,6 @@ def __repr__(self) -> str:
         return '<PRAGMA {}>'.format(self.command)
 
 
-DeclareOffsets = Iterable[Tuple[int, str]]
-
-
 class Declare(AbstractInstruction):
     """
     A DECLARE directive.
@@ -894,7 +891,7 @@ class Declare(AbstractInstruction):
 
     def __init__(self, name: str, memory_type: str, memory_size: int = 1,
                  shared_region: Optional[str] = None,
-                 offsets: Optional[DeclareOffsets] = None):
+                 offsets: Optional[Iterable[Tuple[int, str]]] = None):
         self.name = name
         self.memory_type = memory_type
         self.memory_size = memory_size
@@ -904,7 +901,7 @@ def __init__(self, name: str, memory_type: str, memory_size: int = 1,
             offsets = []
         self.offsets = offsets
 
-    def asdict(self) -> Dict[str, Union[DeclareOffsets, Optional[str], int]]:
+    def asdict(self) -> Dict[str, Union[Iterable[Tuple[int, str]], Optional[str], int]]:
         return {
             'name': self.name,
             'memory_type': self.memory_type,