Skip to content

Commit

Permalink
docs: samples docstring and comments update (#69)
Browse files Browse the repository at this point in the history 
* chore: Updating docstrings to match samples from other languages.

* feat: Fixing comments and docstrings to be in sync with other samples.

* docs: Updating sample docstrings and comments

Applying some changes after consulting with tech writer.
  • Loading branch information
@m-strzelczyk @dandhlee
m-strzelczyk authored and dandhlee committed Nov 16, 2022
1 parent ed970e2 commit 1873fb0
Showing 1 changed file with 29 additions and 46 deletions.
75 changes: 29 additions & 46 deletions compute/compute/snippets/quickstart.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,13 +40,11 @@
# [START compute_instances_list]
def list_instances(project_id: str, zone: str) -> typing.Iterable[compute_v1.Instance]:
"""
Gets a list of instances created in given project in given zone.
Returns an iterable collection of Instance objects.
List all instances in the given zone in the specified project.
Args:
project_id: ID or number of the project you want to use.
zone: Name of the zone you want to check, for example: us-west3-b
project_id: project ID or project number of the Cloud project you want to use.
zone: name of the zone you want to use. For example: “us-west3-b”
Returns:
An iterable collection of Instance objects.
"""
Expand All @@ -58,20 +56,18 @@ def list_instances(project_id: str, zone: str) -> typing.Iterable[compute_v1.Ins
print(f" - {instance.name} ({instance.machine_type})")

return instance_list


# [END compute_instances_list]


# [START compute_instances_list_all]
def list_all_instances(
project_id: str,
) -> typing.Dict[str, typing.Iterable[compute_v1.Instance]]:
"""
Returns a dictionary of all instances present in a project, grouped by their zone.
Return a dictionary of all instances present in a project, grouped by their zone.
Args:
project_id: ID or number of the project you want to use.
project_id: project ID or project number of the Cloud project you want to use.
Returns:
A dictionary with zone names as keys (in form of "zones/{zone_name}") and
iterable collections of Instance objects as values.
Expand All @@ -87,8 +83,6 @@ def list_all_instances(
for instance in response.instances:
print(f" - {instance.name} ({instance.machine_type})")
return all_instances


# [END compute_instances_list_all]


Expand All @@ -102,33 +96,28 @@ def create_instance(
network_name: str = "global/networks/default",
) -> compute_v1.Instance:
"""
Sends an instance creation request to GCP and waits for it to complete.
Send an instance creation request to the Compute Engine API and wait for it to complete.
Args:
project_id: ID or number of the project you want to use.
zone: Name of the zone you want to use, for example: us-west3-b
instance_name: Name of the new machine.
machine_type: Machine type you want to create in following format:
"zones/{zone}/machineTypes/{type_name}". For example:
"zones/europe-west3-c/machineTypes/f1-micro"
You can find the list of available machine types using:
https://cloud.google.com/sdk/gcloud/reference/compute/machine-types/list
source_image: Path the the disk image you want to use for your boot
project_id: project ID or project number of the Cloud project you want to use.
zone: name of the zone you want to use. For example: “us-west3-b”
instance_name: name of the new virtual machine.
machine_type: machine type of the VM being created. This value uses the
following format: "zones/{zone}/machineTypes/{type_name}".
For example: "zones/europe-west3-c/machineTypes/f1-micro"
source_image: path to the operating system image to mount on your boot
disk. This can be one of the public images
(e.g. "projects/debian-cloud/global/images/family/debian-10")
(like "projects/debian-cloud/global/images/family/debian-10")
or a private image you have access to.
You can check the list of available public images using:
$ gcloud compute images list
network_name: Name of the network you want the new instance to use.
For example: global/networks/default - if you want to use the
default network.
network_name: name of the network you want the new instance to use.
For example: "global/networks/default" represents the `default`
network interface, which is created automatically for each project.
Returns:
Instance object.
"""
instance_client = compute_v1.InstancesClient()

# Every machine requires at least one persistent disk
# Describe the size and source image of the boot disk to attach to the instance.
disk = compute_v1.AttachedDisk()
initialize_params = compute_v1.AttachedDiskInitializeParams()
initialize_params.source_image = (
Expand All @@ -140,25 +129,25 @@ def create_instance(
disk.boot = True
disk.type_ = compute_v1.AttachedDisk.Type.PERSISTENT

# Every machine needs to be connected to a VPC network.
# The 'default' network is created automatically in every project.
# Use the network interface provided in the network_name argument.
network_interface = compute_v1.NetworkInterface()
network_interface.name = network_name

# Collecting all the information into the Instance object
# Collect information into the Instance object.
instance = compute_v1.Instance()
instance.name = instance_name
instance.disks = [disk]
full_machine_type_name = f"zones/{zone}/machineTypes/{machine_type}"
instance.machine_type = full_machine_type_name
instance.network_interfaces = [network_interface]

# Preparing the InsertInstanceRequest
# Prepare the request to insert an instance.
request = compute_v1.InsertInstanceRequest()
request.zone = zone
request.project = project_id
request.instance_resource = instance

# Wait for the create operation to complete.
print(f"Creating the {instance_name} instance in {zone}...")
operation = instance_client.insert(request=request)
if operation.status == compute_v1.Operation.Status.RUNNING:
Expand All @@ -172,20 +161,18 @@ def create_instance(
print("Warning during creation:", operation.warnings, file=sys.stderr)
print(f"Instance {instance_name} created.")
return instance


# [END compute_instances_create]


# [START compute_instances_delete]
def delete_instance(project_id: str, zone: str, machine_name: str) -> None:
"""
Sends a delete request to GCP and waits for it to complete.
Send an instance deletion request to the Compute Engine API and wait for it to complete.
Args:
project_id: ID or number of the project you want to use.
zone: Name of the zone you want to use, for example: us-west3-b
machine_name: Name of the machine you want to delete.
project_id: project ID or project number of the Cloud project you want to use.
zone: name of the zone you want to use. For example: “us-west3-b”
machine_name: name of the machine you want to delete.
"""
instance_client = compute_v1.InstancesClient()

Expand All @@ -204,8 +191,6 @@ def delete_instance(project_id: str, zone: str, machine_name: str) -> None:
print("Warning during deletion:", operation.warnings, file=sys.stderr)
print(f"Instance {machine_name} deleted.")
return


# [END compute_instances_delete]


Expand All @@ -220,7 +205,7 @@ def wait_for_operation(
Args:
operation: The Operation object representing the operation you want to
wait on.
project_id: ID or number of the project owning the operation.
project_id: project ID or project number of the Cloud project you want to use.
Returns:
Finished Operation object.
Expand All @@ -232,13 +217,11 @@ def wait_for_operation(
kwargs["zone"] = operation.zone.rsplit("/", maxsplit=1)[1]
elif operation.region:
client = compute_v1.RegionOperationsClient()
# Operation.region is a full URL address of a zone, so we need to extract just the name
# Operation.region is a full URL address of a region, so we need to extract just the name
kwargs["region"] = operation.region.rsplit("/", maxsplit=1)[1]
else:
client = compute_v1.GlobalOperationsClient()
return client.wait(**kwargs)


# [END compute_instances_operation_check]


Expand Down

0 comments on commit 1873fb0

Please sign in to comment.