Skip to content

Commit

Permalink
cleanup engine docstrings (#3319)
Browse files Browse the repository at this point in the history 
Cleanup of method docstrings in the Engine API. 

* some places we had Params instead of Args
* some places we had filter strings for timestamps referring to the long string format which is actually not supported, only epoch timestamps
  • Loading branch information
@balopat
balopat committed Sep 14, 2020
1 parent c53ef33 commit 0f29fae
Showing 1 changed file with 29 additions and 32 deletions.
61 changes: 29 additions & 32 deletions cirq/google/engine/engine_client.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ def get_program(self, project_id: str, program_id: str,
return_code: bool) -> qtypes.QuantumProgram:
"""Returns a previously created quantum program.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
return_code: If True returns the serialized program code.
Expand All @@ -203,7 +203,7 @@ def set_program_description(self, project_id: str, program_id: str,
description: str) -> qtypes.QuantumProgram:
"""Sets the description for a previously created quantum program.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
description: The new program description.
Expand Down Expand Up @@ -238,7 +238,7 @@ def set_program_labels(self, project_id: str, program_id: str,
"""Sets (overwriting) the labels for a previously created quantum
program.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
labels: The entire set of new program labels.
Expand All @@ -254,7 +254,7 @@ def add_program_labels(self, project_id: str, program_id: str,
labels: Dict[str, str]) -> qtypes.QuantumProgram:
"""Adds new labels to a previously created quantum program.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
labels: New labels to add to the existing program labels.
Expand All @@ -277,7 +277,7 @@ def remove_program_labels(self, project_id: str, program_id: str,
"""Removes labels with given keys from the labels of a previously
created quantum program.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
label_keys: Label keys to remove from the existing program labels.
Expand All @@ -302,7 +302,7 @@ def delete_program(self,
delete_jobs: bool = False) -> None:
"""Deletes a previously created quantum program.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
delete_jobs: If True will delete all the program's jobs, other this
Expand Down Expand Up @@ -368,7 +368,7 @@ def get_job(self, project_id: str, program_id: str, job_id: str,
return_run_context: bool) -> qtypes.QuantumJob:
"""Returns a previously created job.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
job_id: Unique ID of the job within the parent program.
Expand All @@ -381,7 +381,7 @@ def set_job_description(self, project_id: str, program_id: str, job_id: str,
description: str) -> qtypes.QuantumJob:
"""Sets the description for a previously created quantum job.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
job_id: Unique ID of the job within the parent program.
Expand Down Expand Up @@ -413,7 +413,7 @@ def set_job_labels(self, project_id: str, program_id: str, job_id: str,
labels: Dict[str, str]) -> qtypes.QuantumJob:
"""Sets (overwriting) the labels for a previously created quantum job.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
job_id: Unique ID of the job within the parent program.
Expand All @@ -430,7 +430,7 @@ def add_job_labels(self, project_id: str, program_id: str, job_id: str,
labels: Dict[str, str]) -> qtypes.QuantumJob:
"""Adds new labels to a previously created quantum job.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
job_id: Unique ID of the job within the parent program.
Expand All @@ -454,7 +454,7 @@ def remove_job_labels(self, project_id: str, program_id: str, job_id: str,
"""Removes labels with given keys from the labels of a previously
created quantum job.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
job_id: Unique ID of the job within the parent program.
Expand All @@ -477,7 +477,7 @@ def remove_job_labels(self, project_id: str, program_id: str, job_id: str,
def delete_job(self, project_id: str, program_id: str, job_id: str) -> None:
"""Deletes a previously created quantum job.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
job_id: Unique ID of the job within the parent program.
Expand All @@ -488,7 +488,7 @@ def delete_job(self, project_id: str, program_id: str, job_id: str) -> None:
def cancel_job(self, project_id: str, program_id: str, job_id: str) -> None:
"""Cancels the given job.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
job_id: Unique ID of the job within the parent program.
Expand All @@ -500,7 +500,7 @@ def get_job_results(self, project_id: str, program_id: str,
job_id: str) -> qtypes.QuantumResult:
"""Returns the results of a completed job.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
program_id: Unique ID of the program within the parent project.
job_id: Unique ID of the job within the parent program.
Expand All @@ -516,7 +516,7 @@ def list_processors(self, project_id: str) -> List[qtypes.QuantumProcessor]:
current Engine project. The names of these processors are used to
identify devices when scheduling jobs and gathering calibration metrics.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
Returns:
Expand All @@ -531,7 +531,7 @@ def get_processor(self, project_id: str,
processor_id: str) -> qtypes.QuantumProcessor:
"""Returns a quantum processor.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
processor_id: The processor unique identifier.
Expand All @@ -549,16 +549,13 @@ def list_calibrations(self,
) -> List[qtypes.QuantumCalibration]:
"""Returns a list of quantum calibrations.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
processor_id: The processor unique identifier.
filter: Filter string current only supports 'timestamp' with values
of epoch time in seconds or short string 'yyyy-MM-dd' or long
string 'yyyy-MM-dd HH:mm:ss.SSS' both in UTC. For example:
of epoch time in seconds or short string 'yyyy-MM-dd'. For example:
'timestamp > 1577960125 AND timestamp <= 1578241810'
'timestamp > 2020-01-02 AND timestamp <= 2020-01-05'
'timestamp > "2020-01-02 10:15:25.000" AND timestamp <=
"2020-01-05 16:30:10.456"'
Returns:
A list of calibrations.
Expand All @@ -574,7 +571,7 @@ def get_calibration(self, project_id: str, processor_id: str,
) -> qtypes.QuantumCalibration:
"""Returns a quantum calibration.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
processor_id: The processor unique identifier.
calibration_timestamp_seconds: The timestamp of the calibration in
Expand All @@ -593,7 +590,7 @@ def get_current_calibration(self, project_id: str, processor_id: str
"""Returns the current quantum calibration for a processor if it has
one.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
processor_id: The processor unique identifier.
Expand All @@ -618,7 +615,7 @@ def create_reservation(self,
whitelisted_users: Optional[List[str]] = None):
"""Creates a quantum reservation and returns the created object.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
processor_id: The processor unique identifier.
reservation_id: Unique ID of the reservation in the parent project,
Expand Down Expand Up @@ -654,7 +651,7 @@ def cancel_reservation(self, project_id: str, processor_id: str,
has already ended or is beyond the processor's freeze window, then the
call will return an error.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
processor_id: The processor unique identifier.
reservation_id: Unique ID of the reservation in the parent project,
Expand All @@ -675,7 +672,7 @@ def delete_reservation(self, project_id: str, processor_id: str,
If the reservation has already ended or is within the processor's
freeze window, then the call will return a `FAILED_PRECONDITION` error.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
processor_id: The processor unique identifier.
reservation_id: Unique ID of the reservation in the parent project,
Expand All @@ -689,7 +686,7 @@ def get_reservation(self, project_id: str, processor_id: str,
reservation_id: str):
""" Gets a quantum reservation from the engine.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
processor_id: The processor unique identifier.
reservation_id: Unique ID of the reservation in the parent project,
Expand All @@ -713,16 +710,16 @@ def list_reservations(self,
Only reservations owned by this project will be returned.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
processor_id: The processor unique identifier.
filter: A string for filtering quantum reservations.
The fields eligible for filtering are start_time and end_time
Examples:
`start_time >= 1584385200`: Reservation began on or after
the epoch time Mar 16th, 7pm GMT.
`end_time >= "2017-01-02 15:21:15.142"`: Reservation ends on
or after Jan 2nd 2017 15:21:15.142
`end_time >= 1483370475`: Reservation ends on
or after Jan 2nd 2017 15:21:15
Returns:
A list of QuantumReservation objects.
Expand All @@ -747,7 +744,7 @@ def update_reservation(self,
and list of whitelisted users. If any field is not filled, it will
not be updated.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
processor_id: The processor unique identifier.
reservation_id: Unique ID of the reservation in the parent project,
Expand Down Expand Up @@ -784,7 +781,7 @@ def list_time_slots(self,
filter_str: str = '') -> List[qtypes.QuantumTimeSlot]:
"""Returns a list of quantum time slots on a processor.
Params:
Args:
project_id: A project_id of the parent Google Cloud Project.
processor_id: The processor unique identifier.
filter: A string expression for filtering the quantum
Expand Down

0 comments on commit 0f29fae

Please sign in to comment.