Fix docs/google snippet error and add to snippets_test (#7803)

The PR fixes the md files' snippet errors under docs/google by adding
test substitution and MagicMock, also fixing some outdated APIs. On the
test side, adding necessary imports for cirq_google to let the tests
being able to find necessary variables.

This also extends the `test_substitution` markup to allow multi-line
replacement text.

Partially implements #7787

---------

Co-authored-by: Pavol Juhas <juhas@google.com>

Author: ToastCheng

dev_tools/snippets_test.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Tests for executable snippets in documentation.
+r"""Tests for executable snippets in documentation.
 
 This tests code snippets that are executable in `.md` documentation. It covers
 all such files under the docs directory, as well as the top-level README file.
@@ -42,10 +42,14 @@
             <!---test_substitution
             pattern
             substitution
+            substitution-line-2
             --->
 
       where pattern is the regex matching pattern (passed to re.compile) and
-      substitution is the replacement string.
+      substitution is the replacement string.  The replacement string may
+      span several lines and it recognizes escape sequences as in `re.sub`,
+      for example, `\1` stands for the text matched by the first parentheses
+      group in the pattern and `\g<0>` for the entire matched string.
 """
 
 from __future__ import annotations
@@ -82,10 +86,10 @@ def test_can_run_readme_code_snippets():
 
 def find_docs_code_snippets_paths() -> Iterator[str]:
     for filename in DOCS_FOLDER.rglob('*.md'):
-        # Skip files under either 'hardware' and 'google'
+        # Skip files under 'hardware'
         # TODO: #7787 - revisit which of these can be fixed and enabled later.
         path = str(filename.relative_to(DOCS_FOLDER))
-        if not path.startswith(('hardware', 'google')):
+        if not path.startswith('hardware'):
             yield path
 
 
@@ -114,7 +118,7 @@ def find_markdown_code_snippets(content: str) -> list[tuple[str, int]]:
 
 def find_markdown_test_overrides(content: str) -> list[tuple[Pattern, str]]:
     test_sub_text = find_code_snippets("<!---test_substitution\n(.*?)--->", content)
-    substitutions = [line.split('\n')[:-1] for line, _ in test_sub_text]
+    substitutions = [line.rstrip().split('\n', maxsplit=1) for line, _ in test_sub_text]
     return [(re.compile(match), sub) for match, sub in substitutions]
 
 
@@ -255,6 +259,9 @@ def assert_code_snippets_run_in_sequence(snippets: list[tuple[str, int]], assume
 
     if assume_import:
         exec('import cirq', state)
+        exec('import cirq_google', state)
+        exec('import unittest.mock as mock', state)
+        exec('import sympy', state)
 
     for content, line_number in snippets:
         assert_code_snippet_executes_correctly(content, state, line_number)

docs/google/calibration.md

@@ -20,12 +20,23 @@ A dropdown menu will let you choose the current characterization or historical
 metrics from a previous run.  Calibration metrics can also be retrieved
 programmatically using an engine instance or with a job.
 
+<!---test_substitution
+engine = cg.Engine\(project_id=.*
+\g<0>
+engine = mock.create_autospec(cirq_google.Engine, instance=True)
+mock_engine_processor = mock.create_autospec(cirq_google.EngineProcessor, instance=True)
+engine.configure_mock(**{"get_processor.return_value": mock_engine_processor})
+--->
+<!---test_substitution
+PROJECT_ID|PROGRAM_ID|PROCESSOR_ID|CALIBRATION_SECONDS|START_SECONDS|END_SECONDS|JOB_ID
+'placeholder'
+--->
 ```python
 import cirq_google as cg
 
 # Create an Engine object to use.
-# Replace YOUR_PROJECT_ID with the id from your cloud project.
-engine = cg.Engine(project_id=YOUR_PROJECT_ID)
+# Replace PROJECT_ID with the id from your cloud project.
+engine = cg.Engine(project_id=PROJECT_ID)
 processor = engine.get_processor(processor_id=PROCESSOR_ID)
 
 # Get the latest calibration metrics.
@@ -36,23 +47,24 @@ latest_calibration = processor.get_current_calibration()
 previous_calibration = processor.get_calibration(CALIBRATION_SECONDS)
 
 # If you would like to find a calibration from a time-frame, use this.
-calibration_list = processor.list_calibration(START_SECONDS, END_SECONDS)
+calibration_list = processor.list_calibrations(START_SECONDS, END_SECONDS)
 
+## TODO: #7910 - fix or delete this block
 # If you know the job-id, you can retrieve the calibration that the job used.
-job = engine.get_job("projects/" + PROJECT_ID
-                   + "/programs/"+PROGRAM_ID
-                   + "/jobs/" + JOB_ID)
-job_calibration = cg.EngineJob(cg.JobConfig(), job, engine).get_calibration()
+# job = engine.get_job("projects/" + PROJECT_ID
+#                    + "/programs/"+ PROGRAM_ID
+#                    + "/jobs/" + JOB_ID)
+# job_calibration = cg.EngineJob(PROJECT_ID, PROGRAM_ID, JOB_ID, cg.engine.engine.EngineContext()).get_calibration()
 
 # The calibration can be iterated through using something like the following.
 for metric_name in latest_calibration:
-  print(metric_name)
-  print('------')
-  for qubit_or_pair in latest_calibration[metric_name]:
-     # Note that although the value is often singular,
-     # the metric_value is of the type list and can have multiple values.
-     metric_value = latest_calibration[metric_name][qubit_or_pair]
-     print(f'{qubit_or_pair} = {metric_value}')
+    print(metric_name)
+    print('------')
+    for qubit_or_pair in latest_calibration[metric_name]:
+        # Note that although the value is often singular,
+        # the metric_value is of the type list and can have multiple values.
+        metric_value = latest_calibration[metric_name][qubit_or_pair]
+        print(f'{qubit_or_pair} = {metric_value}')
 ```
 
 Calibration metrics will also soon be available from the

docs/google/devices.md

@@ -39,7 +39,7 @@ For example, this circuit will execute the two gates in parallel:
 
 ```python
 cirq.Circuit(
-  cirq.Moment(cirq.X(cirq.GridQubit(4,4)), cirq.X(cirq.GridQubit(4,5)))
+    cirq.Moment(cirq.X(cirq.GridQubit(4, 4)), cirq.X(cirq.GridQubit(4, 5)))
 )
 ```
 
@@ -48,8 +48,8 @@ This circuit will execute the two gates in serial:
 
 ```python
 cirq.Circuit(
-  cirq.Moment(cirq.X(cirq.GridQubit(4,4))),
-  cirq.Moment(cirq.X(cirq.GridQubit(4,5)))
+    cirq.Moment(cirq.X(cirq.GridQubit(4, 4))),
+    cirq.Moment(cirq.X(cirq.GridQubit(4, 5))),
 )
 ```
 
@@ -58,8 +58,8 @@ is virtual and its moment will disappear:
 
 ```python
 cirq.Circuit(
-  cirq.Moment(cirq.Z(cirq.GridQubit(4,4))),
-  cirq.Moment(cirq.X(cirq.GridQubit(4,5)))
+    cirq.Moment(cirq.Z(cirq.GridQubit(4, 4))),
+    cirq.Moment(cirq.X(cirq.GridQubit(4, 5))),
 )
 ```
 
@@ -89,7 +89,7 @@ in 0.02 increments.
 
 
 ```python
-descriptor = cirq_google.study.DeviceParameter( ["q4_8", "piAmp"])
+descriptor = cirq_google.study.DeviceParameter(["q4_8", "piAmp"])
 sweep = cirq.Linspace("q4_8.piAmp", 0, 1, 51, metadata=descriptor)
 ```
 
@@ -295,9 +295,9 @@ It can be accessed by using `cirq_google.Sycamore`. This device has two possible
 two-qubits gates that can be used.
 
 *  Square root of ISWAP. The gate `cirq.ISWAP ** 0.5` or `cirq.ISWAP ** -0.5` can be
-used on this device.
+   used on this device.
 *  Sycamore gate. This gate, equivalent to FSimGate(π/2, π/6) can be used as `cirq_google.SYC`
-or by using `cirq.FsimGate(numpy.pi/2,numpy.pi/6)`. 
+   or by using `cirq.FsimGate(numpy.pi/2,numpy.pi/6)`.
 
 
 ### Sycamore23

docs/google/engine.md

@@ -23,6 +23,10 @@ gcloud client:
 
 From a colab, you can execute:
 
+<!---test_substitution
+from google\.colab import auth
+auth = mock.MagicMock()
+--->
 ```python
 from google.colab import auth
 auth.authenticate_user(clear_output=False)
@@ -41,42 +45,52 @@ You can use this instance to run quantum circuits or sweeps (parameterized
 variants of a general circuit).
 
 <!---test_substitution
-results = job.results.*
-results = None
---->
-<!---test_substitution
-print.results.idx.*
-print()
+engine = cirq_google.Engine\b.*
+# This pattern matches in all snippets.
+# We repeat the expression first to ensure Engine argumets are correct.
+\g<0>
+# Then we create various mock objects that derive from engine calls.
+engine = mock_engine = mock.create_autospec(cirq_google.Engine, instance=True)
+mock_sampler = mock.create_autospec(cirq.Sampler, instance=True)
+mock_engine_job = mock.create_autospec(cirq_google.EngineJob, instance=True,
+    program_id="program_id", job_id="job_id")
+mock_engine_program = mock.create_autospec(cirq_google.EngineProgram, instance=True,
+    program_id="program_id")
+# Finally let us import datetime for snippets that use it below
+import datetime
 --->
 <!---test_substitution
-engine = cirq_google.Engine(.*)
-engine = MockEngine()
+sampler = engine.get_sampler.processor_id=PROCESSOR_ID.*
+mock_engine.configure_mock(**{"get_sampler.return_value": mock_sampler})
+\g<0>
 --->
 <!---test_substitution
-cg.Engine(.*)
-cirq.Simulator()
+results = sampler.run\b
+mock_result = mock.create_autospec(cirq.Result, instance=True)
+mock_sampler.configure_mock(**{"run.return_value": mock_result})
+\g<0>
 --->
 <!---test_substitution
-sampler = .*
-sampler = engine
+PROJECT_ID|PROCESSOR_ID
+'placeholder'
 --->
 ```python
 import cirq
-import cirq_google as cg
+import cirq_google
 
 # A simple sample circuit
 qubit = cirq.GridQubit(5, 2)
 circuit = cirq.Circuit(
-    cirq.X(qubit)**0.5,                 # Square root of NOT.
-    cirq.measure(qubit, key='result')   # Measurement.
+    cirq.X(qubit) ** 0.5,  # Square root of NOT.
+    cirq.measure(qubit, key='result'),  # Measurement.
 )
 
 # Create an Engine object.
-# Replace YOUR_PROJECT_ID with the id from your cloud project.
-engine = cg.Engine(project_id=YOUR_PROJECT_ID)
+# Replace PROJECT_ID with the id from your cloud project.
+engine = cirq_google.Engine(project_id=PROJECT_ID)
 
 # Create a sampler from the engine
-sampler = engine.get_sampler(processor_id='PROCESSOR_ID')
+sampler = engine.get_sampler(processor_id=PROCESSOR_ID)
 
 # This will run the circuit and return the results in a 'Result'
 results = sampler.run(circuit, repetitions=1000)
@@ -152,26 +166,36 @@ Currently, getting the program and job ids can only be done through the
 You can then use `get_program` and `get_job` to retrieve the results.
 See below for an example:
 
+<!---test_substitution
+job = engine.run_sweep.program=circuit
+mock_engine.configure_mock(**{
+    "run_sweep.return_value": mock_engine_job,
+    "get_program.return_value": mock_engine_program,
+})
+mock_engine_program.configure_mock(**{"get_job.return_value": mock_engine_job})
+\g<0>
+--->
 ```python
 # Initialize the engine object
-engine = cirq_google.Engine(project_id='YOUR_PROJECT_ID')
+engine = cirq_google.Engine(project_id=PROJECT_ID)
 
 # Create an example circuit
 qubit = cirq.GridQubit(5, 2)
 circuit = cirq.Circuit(
-    cirq.X(qubit)**sympy.Symbol('t'),
-    cirq.measure(qubit, key='result')
+    cirq.X(qubit) ** sympy.Symbol('t'),
+    cirq.measure(qubit, key='result'),
 )
 param_sweep = cirq.Linspace('t', start=0, stop=1, length=10)
 
 # Run the circuit
-job = e.run_sweep(program=circuit,
-                  params=param_sweep,
-                  repetitions=1000,
-                  processor_id='PROCESSOR_ID',
-                  gate_set=GATE_SET)
+job = engine.run_sweep(
+    program=circuit,
+    params=param_sweep,
+    repetitions=1000,
+    processor_id=PROCESSOR_ID,
+)
 
-# Save the program and jo id for later
+# Save the program and job id for later
 program_id = job.program_id
 job_id = job.job_id
 
@@ -187,7 +211,6 @@ historical_job = engine.get_program(program_id=program_id).get_job(job_id=job_id
 
 # Retrieve the results
 historical_results = historical_job.results()
-
 ```
 
 If you did not save the ids, you can still find them from your
@@ -200,17 +223,24 @@ by using our list methods.
 To list the executions of your circuit, i.e., the jobs, you can use `cirq_google.Engine.list_jobs()`.
 You can search in all the jobs within your project using filtering criteria on creation time, execution state and labels.
 
+<!---test_substitution
+jobs = engine.list_jobs.created_after=datetime.date.*
+mock_engine.configure_mock(**{"list_jobs.return_value": [mock_engine_job]})
+\g<0>
+--->
 ```python
-from cirq_google.engine.client.quantum import enums
+from cirq_google.cloud import quantum
 
 # Initialize the engine object
-engine = cirq_google.Engine(project_id='YOUR_PROJECT_ID')
+engine = cirq_google.Engine(project_id=PROJECT_ID)
 
 # List all the jobs on the project since 2020/09/20 that succeeded:
-jobs = engine.list_jobs(created_after=datetime.date(2020,9,20),
-                        execution_states=[enums.ExecutionStatus.State.SUCCESS])
+jobs = engine.list_jobs(
+    created_after=datetime.date(2020, 9, 20),
+    execution_states=[quantum.ExecutionStatus.State.SUCCESS],
+)
 for j in jobs:
-   print(j.job_id, j.status(), j.create_time())
+    print(j.job_id, j.status(), j.create_time())
 ```
 
 ### Listing programs
@@ -219,23 +249,29 @@ To list the different instances of your circuits uploaded, i.e., the programs, y
 Similar to jobs, filtering makes it possible to list programs by creation time and labels.
 With an existing `cirq_google.EngineProgram` object, you can list any jobs that were run using that program.
 
+<!---test_substitution
+programs = engine.list_programs[(].*
+mock_engine.configure_mock(**{"list_programs.return_value": [mock_engine_program]})
+mock_engine_program.configure_mock(**{"list_jobs.return_value": [mock_engine_job]})
+\g<0>
+--->
 ```python
-from cirq_google.engine.client.quantum import enums
+from cirq_google.cloud import quantum
 
 # Initialize the engine object
-engine = cirq_google.Engine(project_id='YOUR_PROJECT_ID')
+engine = cirq_google.Engine(project_id=PROJECT_ID)
 
 # List all the programs on the project since 2020/09/20 that have
 # the "variational" label with any value and the "experiment" label
 # with value "vqe001":
 programs = engine.list_programs(
-                created_after=datetime.date(2020,9,20),
-                has_labels={"variational":"*", "experiment":"vqe001"}
-           )
+    created_after=datetime.date(2020, 9, 20),
+    has_labels={"variational": "*", "experiment": "vqe001"},
+)
 for p in programs:
-   print(p.program_id, p.create_time())
-   # the same filtering parametrization is available as in engine.list_jobs()
-   # for example here we list the jobs under the programs that failed
-   for j in p.list_jobs(execution_states=[enums.ExecutionStatus.State.FAILURE]):
-     print(j.job_id, j.status())
+    print(p.program_id, p.create_time())
+    # the same filtering parametrization is available as in engine.list_jobs()
+    # for example here we list the jobs under the programs that failed
+    for j in p.list_jobs(execution_states=[quantum.ExecutionStatus.State.FAILURE]):
+        print(j.job_id, j.status())
 ```