V4 - feat: A new diagnostics module has been added. (#1628)

* feat: A new `diagnostics` module has been added. The `get_report`
function can be used to get a gather and report on various diaganostics.

* fix testoutput annotation

* add test

* Add `PRAGMA DELAY ...` breaking change

* bump qcs-sdk-python

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 4.0.0
 
-The 4.0 release of pyQuil migrates its core functionality into Rigetti's latest generation of Rust SDKs. With this comes access to new features, improved performance, stronger type safety, and better error messages. While this is a significant change for the internals of pyQuil, we've attempted to keep breaking changes to a minimum. Unless necessary, we've chosen to only remove redunant or lesser used features that aren't likely to bother most users.
+The 4.0 release of pyQuil migrates its core functionality into Rigetti's latest generation of Rust SDKs. With this comes access to new features, improved performance, stronger type safety, and better error messages. While this is a significant change for the internals of pyQuil, we've attempted to keep breaking changes to a minimum. Unless necessary, we've chosen to only remove redundant or lesser used features that aren't likely to bother most users.
 
 ### Breaking Changes
 
@@ -12,6 +12,7 @@ The 4.0 release of pyQuil migrates its core functionality into Rigetti's latest
 - Python 3.7 is no longer supported.
 - The environment variable overrides for `quilc` and `QVM` URLs have been renamed to `QCS_APPLICATIONS_QUILC_URL` and `QCS_APPLICATIONS_QVM_URL`, respectively.
 - The `QuantumComputer`'s `run` method now takes an optional `memory_map` parameter. This mapping takes memory region names to a list of values to use for a run. This replaces the ability to use `write_memory` on `Program`s.
+- `Pragma("DELAY", ...)` will now raise a parser error because it generates invalid Quil. Use the `Delay` instruction instead.
 
 ### Features
 
@@ -21,6 +22,8 @@ The 4.0 release of pyQuil migrates its core functionality into Rigetti's latest
 	- Better error messages when a request fails
 - The improved Rust backend allows on-demand access to a QPU.
 - The new `QPUCompilerAPIOptions` class provides can now be used to customize how a program is compiled against a QPU.
+- The `diagnostics` module has been introduced with a `get_report` function that will gather information on the currently running pyQuil
+installation, perform diagnostics checks, and return a summary.
 
 ## 3.5.4
 

docs/source/troubleshooting.rst

@@ -7,7 +7,7 @@ If you're having any trouble running your pyQuil programs locally or on the QPU,
 following things before sending a support request. It will save you time and make it easier for us
 to help!
 
-Timeout in Compilation
+Timeout in compilation
 ----------------------
 
 This may occur due to the size of your program, problems with your local ``quilc`` service, or problems
@@ -18,26 +18,26 @@ with the remote QCS API.
 3. If you have a larger program and expect it to take a long time to compile, set a higher ``compiler_timeout``
    value per the instructions here: :ref:`compiler`.
 
-Timeout in Execution
+Timeout in execution
 --------------------
 
 This may occur due to one of several different problems. Often, it's because you don't have network access
 to the execution endpoint.
 
-If you're running against the QVM, ensure that it is properly running: :ref:`server`. If you're using docker,
+If you're running against the QVM, ensure that it's running: :ref:`server`. If you're using docker,
 you can check this using ``docker ps``.
 
 If you're running against the QPU, ensure that you are running your program from a supported environment.
 Live Rigetti QPUs are **only accessible from Rigetti-provided environments**, such as
 `JupyterHub <https://jupyterhub.qcs.rigetti.com>`_. If you are running from anywhere else, such as a
 script on your local computer or a public cloud virtual machine,
-**your program will not be able to reach a QPU and will time out**.
+**your program won't be able to reach a QPU and will time out**.
 
-Collect Debug Information
-----------------------------
+Collect debug information
+-------------------------
 
 1. Ensure that your pyQuil version is up to date. If you're using ``pip``, you can do this with
-   ``pip freeze``. Within your script, you can use ``__version__``:
+   ``pip show pyquil``. Within your script, you can use ``__version__``:
 
    .. testcode:: version
 
@@ -51,28 +51,41 @@ Collect Debug Information
 
    You can update pyQuil with ``pip`` using ``pip install pyquil --upgrade``. You can find
    the latest version available at
-   `our releases page <https://github.com/rigetti/pyquil/releases>`_ or
+   `the releases page <https://github.com/rigetti/pyquil/releases>`_ or
    `on PyPi <https://pypi.org/project/pyquil/>`_.
 
-2. If the error appears to be authentication-related, refer to the `QCS CLI documentation
-<https://docs.rigetti.com>`_.
 
-3. Run your script with debug logging enabled. If you're running a script, you can enable that
-   using an environment variable:
+2. pyQuil exposes a diagnostics report that prints helpful debugging information, including
+   whether you have connectivity to ``quilc``, ``QVM`` and access to QCS services. You can
+   use it by importing a function from the ``diagnostics`` module:
+
+   .. testcode:: version
+
+    from pyquil.diagnostics import get_report
+    print(get_report())
+
+   .. testoutput:: version
+      :hide:
+
+      ...
+
+   Use this report to confirm you have connectivity to the services you need and that your
+   environment matches what you expect.
 
-   .. code::
 
-    LOG_LEVEL=DEBUG pyquil my_script.py
+3. Run your script with debug logging enabled by adding the following to the top of your script:
 
    .. testcode:: python
 
     import logging
-    from pyquil.api._logger import logger
+    logging.basicConfig(level=logging.DEBUG)
 
-    logger.setLevel(logging.DEBUG)
+   .. note:: For information on how to filter the logs, see the `qcs-sdk-python logging documentation <https://github.com/rigetti/qcs-sdk-rust/tree/main/crates/python#enabling-debug-logging>`_
 
 If the problem still isn't clear, then we can help! Please file an issue
 on the `GitHub repo <https://github.com/rigetti/pyquil>`_ if it's an issue with pyQuil itself,
-or contact us at our `support page <https://rigetti.zendesk.com>`_ for problems with QCS.
+or contact us at our `support page <https://rigetti.zendesk.com>`_ for problems with QCS. If applicable,
+be sure to include the diagnostics report and debug logs from above as they will help us better
+diagnose the problem.
 
 Thanks for using pyQuil!

pyproject.toml

@@ -28,8 +28,7 @@ rpcq = "^3.10.0"
 pydantic = "^1.10.7"
 networkx = ">=2.5"
 importlib-metadata = { version = ">=3.7.3,<5", python = "<3.8" }
-qcs-sdk-python = "0.10.3-rc.1"
-quil = "0.1.1"
+qcs-sdk-python = "0.10.8"
 tenacity = "^8.2.2"
 types-python-dateutil = "^2.8.19"
 types-retry = "^0.9.9"

pyquil/diagnostics.py

@@ -0,0 +1,14 @@
+import pyquil
+from qcs_sdk import diagnostics
+
+
+def get_report() -> str:
+    """
+    Get a report of the current state of the pyQuil installation, Python environment,
+    and supporting packages.
+
+    Note: this format is not stable and its content may change between versions.
+    """
+    return f"""pyQuil version: {pyquil.__version__}
+{diagnostics.get_report()}
+"""

test/unit/test_diagnostics.py

@@ -0,0 +1,7 @@
+import pyquil
+from pyquil.diagnostics import get_report
+
+
+def test_report():
+    report = get_report()
+    assert report.split("\n").pop(0) == "pyQuil version: {}".format(pyquil.__version__)