Loaders Reference

botocore.loaders

Module for loading various model files.

This module provides the classes that are used to load models used by botocore. This can include:

  • Service models (e.g. the model for EC2, S3, DynamoDB, etc.)
  • Service model extras which customize the service models
  • Other models associated with a service (pagination, waiters)
  • Non service-specific config (Endpoint data, retry config)

Loading a module is broken down into several steps:

  • Determining the path to load
  • Search the data_path for files to load
  • The mechanics of loading the file
  • Searching for extras and applying them to the loaded file

The last item is used so that other faster loading mechanism besides the default JSON loader can be used.

The Search Path

Similar to how the PATH environment variable is to finding executables and the PYTHONPATH environment variable is to finding python modules to import, the botocore loaders have the concept of a data path exposed through AWS_DATA_PATH.

This enables end users to provide additional search paths where we will attempt to load models outside of the models we ship with botocore. When you create a Loader, there are two paths automatically added to the model search path:

  • <botocore root>/data/
  • ~/.aws/models

The first value is the path where all the model files shipped with botocore are located.

The second path is so that users can just drop new model files in ~/.aws/models without having to mess around with the AWS_DATA_PATH.

The AWS_DATA_PATH using the platform specific path separator to separate entries (typically : on linux and ; on windows).

Directory Layout

The Loader expects a particular directory layout. In order for any directory specified in AWS_DATA_PATH to be considered, it must have this structure for service models:

<root>
  |
  |-- servicename1
  |   |-- 2012-10-25
  |       |-- service-2.json
  |-- ec2
  |   |-- 2014-01-01
  |   |   |-- paginators-1.json
  |   |   |-- service-2.json
  |   |   |-- waiters-2.json
  |   |-- 2015-03-01
  |       |-- paginators-1.json
  |       |-- service-2.json
  |       |-- waiters-2.json
  |       |-- service-2.sdk-extras.json

That is:

  • The root directory contains sub directories that are the name of the services.
  • Within each service directory, there's a sub directory for each available API version.
  • Within each API version, there are model specific files, including (but not limited to): service-2.json, waiters-2.json, paginators-1.json

The -1 and -2 suffix at the end of the model files denote which version schema is used within the model. Even though this information is available in the version key within the model, this version is also part of the filename so that code does not need to load the JSON model in order to determine which version to use.

The sdk-extras and similar files represent extra data that needs to be applied to the model after it is loaded. Data in these files might represent information that doesn't quite fit in the original models, but is still needed for the sdk. For instance, additional operation parameters might be added here which don't represent the actual service api.

class botocore.loaders.ExtrasProcessor

Processes data from extras files into service models.

process(original_model, extra_models)

Processes data from a list of loaded extras files into a model

Parameters
  • original_model (dict) -- The service model to load all the extras into.
  • extra_models (iterable of dict) -- A list of loaded extras models.
class botocore.loaders.JSONFileLoader

Loader JSON files.

This class can load the default format of models, which is a JSON file.

exists(file_path)

Checks if the file exists.

Parameters
file_path (str) -- The full path to the file to load without the '.json' extension.
Returns
True if file path exists, False otherwise.
load_file(file_path)

Attempt to load the file path.

Parameters
file_path (str) -- The full path to the file to load without the '.json' extension.
Returns
The loaded data if it exists, otherwise None.
class botocore.loaders.Loader(extra_search_paths=None, file_loader=None, cache=None, include_default_search_paths=True, include_default_extras=True)

Find and load data models.

This class will handle searching for and loading data models.

The main method used here is load_service_model, which is a convenience method over load_data and determine_latest_version.

BUILTIN_DATA_PATH = '/home/docs/checkouts/readthedocs.org/user_builds/botocore/envs/latest/lib/python2.7/site-packages/botocore-1.7.16-py2.7.egg/botocore/data'
BUILTIN_EXTRAS_TYPES = ['sdk']
CUSTOMER_DATA_PATH = '/home/docs/.aws/models'
FILE_LOADER_CLASS

alias of JSONFileLoader

determine_latest_version(*args, **kwargs)
extras_types
list_api_versions(*args, **kwargs)
list_available_services(*args, **kwargs)
load_data(*args, **kwargs)
load_service_model(*args, **kwargs)
search_paths
botocore.loaders.create_loader(search_path_string=None)

Create a Loader class.

This factory function creates a loader given a search string path.

Parameters
search_string_path (str) -- The AWS_DATA_PATH value. A string of data path values separated by the os.path.pathsep value, which is typically : on POSIX platforms and ; on windows.
Returns
A Loader instance.
botocore.loaders.instance_cache(func)

Cache the result of a method on a per instance basis.

This is not a general purpose caching decorator. In order for this to be used, it must be used on methods on an instance, and that instance must provide a self._cache dictionary.