Boto3 Services

Classes wrapping ServiceResource objects.

The methods and arguments on these classes somtimes differ in name from those in Boto3’s Resources to make them easier to understand in this context..

Glossary:
service_name:

The snake_case name of an AWS service (e.g. ec2)

resource_type:

The (unpluralised) snake_case name of the type of the resource in snake case (e.g. instance)

secondary_attribute:

An attribute of a resource which requires a secondary API call to retrieve (e.g. VPC Attributes)

subresource:

A child resource which does not have its own ARN and must be queried by referencing its parent resource’s ID (e.g. inline role policies). Different from Boto3 subresources which simply indicate a hierarchical relationship between resources (e.g. subnets are a child resource of vpcs).

class Boto3Services(boto3_session=None, service_loader=None, service_mapping_loader=None, account_id=None)

Wraps Boto3 Session.

Allows us to:

  1. Wrap Boto3 ServiceResource objects with CloudWandererBoto3Service objects.

  2. Inject custom service definitions into our CloudWandererBoto3ResourceFactory and return them alongside the default Boto3 ServiceResource objects.

Used by CloudWandererAWSInterface to instantiate services and can be used to get resources from their URN.

__init__(boto3_session=None, service_loader=None, service_mapping_loader=None, account_id=None)

Initialise the Boto3SessionWrapper.

Parameters
Return type

None

account_id

Return the AWS Account ID our Boto3 session is authenticated against.

property available_services

Return a list of service names that can be loaded by Boto3Services.get_service().

get_empty_service(service_name, region_name=None)

Return the :class`CloudWandererBoto3Service` by this name without a Boto3 Client instantiated.

Useful for querying service/resource metadata.

Parameters
  • service_name (str) – The name of the service to instantiate.

  • region_name (Optional[str]) – The region to instantiate the service for.

Return type

cloudwanderer.boto3_services.CloudWandererBoto3Service

get_resource_from_urn(urn)

Return the CloudWandererBoto3Resource resource picked out by this urn.

Parameters

urn (URN) – The urn of the resource to get.

Raises
  • BadUrnAccountIdError – When the account ID of the URN does not match the account id of the current session.

  • BadUrnRegionError – When the region of the URN is not possible with the service and/or resource type.

Return type

cloudwanderer.boto3_services.CloudWandererBoto3Resource

get_service(service_name, region_name=None, **kwargs)

Return the :class`CloudWandererBoto3Service` by this name.

Parameters
  • service_name (str) – The name of the service to instantiate.

  • region_name (Optional[str]) – The region to instantiate the service for.

  • **kwargs – Additional keyword args will be passed to the Boto3 client.

Return type

cloudwanderer.boto3_services.CloudWandererBoto3Service

class CloudWandererBoto3Resource(account_id, boto3_resource, cloudwanderer_boto3_service, service_map)

Wraps Boto3 ServiceResource resource-level objects.

Allows us to provide additional functionality specific to CloudWanderer.

This is almost always tied to a specific resource that exists in AWS, but is occasionally instantiated abstractly in order to interrogate metadata about this resource type.

property get_and_cleanup_actions

Return the query and cleanup actions to be performed if getting this resource type in this region.

get_secondary_attributes()

Return the secondary attributes for this resource.

Return type

Generator[cloudwanderer.cloud_wanderer_resource.SecondaryAttribute, None, None]

get_subresources()

Return the CloudWanderer style subresources of this resource.

Return type

Generator[cloudwanderer.boto3_services.CloudWandererBoto3Resource, None, None]

property id

Return the resource ID.

property is_subresource

Return whether or not this resource is a subresource.

property normalised_raw_data

Return the raw data ditionary for this resource, ensuring that all keys for this resource are present.

property parent_resource_type

Return the resource type of the parent (if it has one).

property raw_data

Return the raw dictionary data for this resource.

property region

Return the region for this resource.

Typically this just takes the region of the session the resource was discovered from. However for some resources (e.g. S3 buckets) it performs an API call to look it up.

property resource_type

Return the snake_case resource type of this resource.

property resource_type_pascal

Return a friendly name for this resource type.

property secondary_attribute_models

Return the secondary attribute models it’s possible for this resource type to have.

property secondary_attribute_names

Return a list fof secondary attributes its possible for this resource type to have.

property service

Return the snake_case service type for this resource.

property subresource_models

Yield the Boto3 models for the CloudWanderer style subresources of this resource type.

property subresource_summary

Return a summary of subresource types in this resource.

property subresource_types

Return a list of CloudWanderer style subresource types it’s possible for this resource type to have.

property urn

Return the resource’s Universal Resource Name.

class CloudWandererBoto3ResourceFactory(boto3_session=None)

Factory class for generating Boto3 Resource objects.

__init__(boto3_session=None)

Initialise the ResourceFactory.

Parameters

boto3_session (boto3.session.Session) – The boto3.session.Session object to use for any queries.

Return type

None

load(service_name, resource_definitions, service_definition)

Load the specified resource definition dictionaries into a Resource object.

Parameters
  • service_name (str) – The name of the service to load (e.g. 'ec2')

  • resource_definitions (dict) – A dict describing the resource definitions. This is the 'resources' key in each resource_definition json.

  • service_definition (dict) – A dict describing the service definition. This is the 'service' key in each resource_definition json.

Return type

Type

class CloudWandererBoto3Service(boto3_service, service_map, account_id, boto3_session, region_name=None, enabled_regions=None)

Wraps Boto3 ServiceResource service-level objects.

Allows us to include additional CloudWanderer specific functionality. The object represents an AWS service (e.g. ec2) in a specific region. Used to get resources from the API as well as get metadata about the resource type from Boto3.

__init__(boto3_service, service_map, account_id, boto3_session, region_name=None, enabled_regions=None)

Instantiate CloudWandererBoto3Service.

Parameters
  • boto3_service (boto3.resources.base.ServiceResource) – The boto3 service object to wrap.

  • service_map (cloudwanderer.boto3_loaders.ServiceMap) – The CloudWanderer service map that provides additional context about this service.

  • account_id (str) – The ID of the AWS account our session is in.

  • region_name (Optional[str]) – The region to get resources from for this service.

  • boto3_session (boto3.session.Session) – The Boto3 session that created this client.

  • enabled_regions (Optional[List[str]]) – The list of regions currently enabled.

Return type

None

property enabled_regions

Return a list of enabled regions in this account.

property friendly_name

Return the friendly name of this service.

property get_regions_discovered_from_region

Return a list of regions resources will have been discovered in by querying this resource in this region.

get_resource_from_urn(urn)

Return the CloudWandererBoto3Resource resource picked out by this urn.

Parameters

urn (URN) – The urn of the resource to get.

Raises
  • BadRequestError – Occurs when the AWS API returns a 4xx HTTP error other than 404.

  • ResourceNotFoundError – Occurs when the AWS API Returns a 404 HTTP error.

  • UnsupportedResourceTypeError – Occurs when the definition for the resource does not support loading by id.

  • botocore.exceptions.ClientError – Boto3 Client Error

  • BadUrnIdentifiersError – Occurs when the URN contains fewer identifiers than is required by the reource type.

Return type

cloudwanderer.boto3_services.CloudWandererBoto3Resource

get_resources(resource_type)

Yield all resources of resource_type in this region.

Parameters

resource_type (str) – The snake_case resource type to get.

Return type

Generator[cloudwanderer.boto3_services.CloudWandererBoto3Resource, None, None]

property name

Return the snake_case name of this service.

property region

Return the name of the region this service is querying.

property resource_summary

Return a summary of resource types in this service.

property resource_types

Return a list of snake_case resource types available on this service.

property should_query_resources_in_region

Return whether this service’s resources should be queried from this region.

class ResourceSummary(resource_type, resource_type_pascal, service_friendly_name, subresources, secondary_attribute_names)

A summary of a resource’s subresource types and secondary attribute names.

property resource_type

Alias for field number 0

property resource_type_pascal

Alias for field number 1

property secondary_attribute_names

Alias for field number 4

property service_friendly_name

Alias for field number 2

property subresources

Alias for field number 3