Fix docs/google snippet error and add to snippets_test

dev_tools/snippets_test.py

@@ -82,10 +82,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 +114,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]
 
 
@@ -256,6 +256,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('from unittest.mock import MagicMock', 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,24 @@ 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(.*)
+engine = MagicMock()
+--->
+<!---test_substitution
+cg.EngineJob(.*)
+MagicMock()
+--->
+<!---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.
@@ -40,9 +52,9 @@ calibration_list = processor.list_calibration(START_SECONDS, END_SECONDS)
 
 # 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
+                   + "/programs/"+ PROGRAM_ID
                    + "/jobs/" + JOB_ID)
-job_calibration = cg.EngineJob(cg.JobConfig(), job, engine).get_calibration()
+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:

docs/google/engine.md

@@ -23,6 +23,10 @@ gcloud client:
 
 From a colab, you can execute:
 
+<!---test_substitution
+from google\.colab import auth
+auth = MagicMock()
+--->
 ```python
 from google.colab import auth
 auth.authenticate_user(clear_output=False)
@@ -50,7 +54,7 @@ print()
 --->
 <!---test_substitution
 engine = cirq_google.Engine(.*)
-engine = MockEngine()
+engine = MagicMock()
 --->
 <!---test_substitution
 cg.Engine(.*)
@@ -60,6 +64,10 @@ cirq.Simulator()
 sampler = .*
 sampler = engine
 --->
+<!---test_substitution
+PROJECT_ID|PROCESSOR_ID
+'placeholder'
+--->
 ```python
 import cirq
 import cirq_google as cg
@@ -72,11 +80,11 @@ circuit = cirq.Circuit(
 )
 
 # 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 = cg.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,9 +160,17 @@ 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
+engine = cg.Engine(.*)
+engine = MagicMock()
+--->
+<!---test_substitution
+GATE_SET
+'placeholder'
+--->
 ```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)
@@ -165,10 +181,10 @@ circuit = cirq.Circuit(
 param_sweep = cirq.Linspace('t', start=0, stop=1, length=10)
 
 # Run the circuit
-job = e.run_sweep(program=circuit,
+job = engine.run_sweep(program=circuit,
                   params=param_sweep,
                   repetitions=1000,
-                  processor_id='PROCESSOR_ID',
+                  processor_id=PROCESSOR_ID,
                   gate_set=GATE_SET)
 
 # Save the program and jo id for later
@@ -200,15 +216,23 @@ 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
+datetime
+MagicMock()
+--->
+<!---test_substitution
+quantum\.ExecutionStatus
+cirq_google.cloud.quantum.ExecutionStatus
+--->
 ```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])
+                        execution_states=[quantum.ExecutionStatus.State.SUCCESS])
 for j in jobs:
    print(j.job_id, j.status(), j.create_time())
 ```
@@ -220,10 +244,10 @@ Similar to jobs, filtering makes it possible to list programs by creation time a
 With an existing `cirq_google.EngineProgram` object, you can list any jobs that were run using that program.
 
 ```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
@@ -236,6 +260,6 @@ 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]):
+   for j in p.list_jobs(execution_states=[quantum.ExecutionStatus.State.FAILURE]):
      print(j.job_id, j.status())
 ```

docs/google/specification.md

@@ -36,14 +36,22 @@ specification.  This time is stored as an integer number of picoseconds.
 Example code to print out the gate durations for every gate supported by the
 device is shown below:
 
+<!---test_substitution
+PROJECT_ID|PROCESSOR_ID
+'placeholder'
+--->
+<!---test_substitution
+engine = cg.Engine(.*)
+engine = MagicMock()
+--->
 ```python
-import cirq
+import cirq_google as cg
 
 # Create an Engine object to use.
-engine = cirq_google.Engine(project_id='your_project_id')
+engine = cg.Engine(project_id=PROJECT_ID)
 
 # Replace the processor id to get the device specification with that id.
-spec = engine.get_processor('processor_id').get_device_specification()
+spec = engine.get_processor(PROCESSOR_ID).get_device_specification()
 
 # Iterate through each gate set valid on the device.
 for gateset in spec.valid_gate_sets:
@@ -99,16 +107,23 @@ verify a circuit.
 The following example illustrates retrieving the device specification live
 from the engine and then using it to validate a circuit.
 
+<!---test_substitution
+PROJECT_ID|PROCESSOR_ID
+'placeholder'
+--->
+<!---test_substitution
+engine = cg.Engine(.*)
+engine = MagicMock()
+--->
 ```python
 import cirq
 import cirq_google as cg
 
 # Create an Engine object to use.
-engine = cg.Engine(project_id='your_project_id',
-                   proto_version=cirq_google.ProtoVersion.V2)
+engine = cg.Engine(project_id=PROJECT_ID, proto_version=cirq_google.ProtoVersion.V2)
 
 # Replace the processor id to get the device with that id.
-device = engine.get_processor('processor_id').get_device()
+device = engine.get_processor(PROCESSOR_ID).get_device()
 
 q0, q1 = cirq.LineQubit.range(2)
 circuit = cirq.Circuit(cirq.CZ(q0, q1))