62 lines
2.4 KiB
ReStructuredText
62 lines
2.4 KiB
ReStructuredText
Design Notes for Botocore
|
|
=========================
|
|
|
|
This document outlines the rationale behind various design
|
|
decisions in botocore.
|
|
|
|
|
|
Casing of Arguments
|
|
-------------------
|
|
|
|
One of the most noticeable differences between botocore and boto
|
|
is that the client objects 1) require parameters to be provided
|
|
as ``**kwargs`` and 2) require the arguments typically be provided as
|
|
``CamelCased`` values.
|
|
|
|
For example::
|
|
|
|
ddb = session.create_client('dynamodb')
|
|
ddb.describe_table(TableName='mytable')
|
|
|
|
In boto, the equivalent code would be::
|
|
|
|
layer1.describe_table(table_name='mytable')
|
|
|
|
There are several reasons why this was changed in botocore.
|
|
|
|
The first reason was because we wanted to have the same casing for
|
|
inputs as well as outputs. In both boto and botocore, the response
|
|
for the ``describe_table`` calls is::
|
|
|
|
{'Table': {'CreationDateTime': 1393007077.387,
|
|
'ItemCount': 0,
|
|
'KeySchema': {'HashKeyElement': {'AttributeName': 'foo',
|
|
'AttributeType': 'S'}},
|
|
'ProvisionedThroughput': {'ReadCapacityUnits': 5,
|
|
'WriteCapacityUnits': 5},
|
|
'TableName': 'testtable',
|
|
'TableStatus': 'ACTIVE'}}
|
|
|
|
Notice that the response is ``CamelCased``. This makes it more difficult
|
|
to round trip results. In many cases you want to get the result of
|
|
a ``describe*`` call and use that value as input through a corresponding
|
|
``update*`` call. If the input arguments require ``snake_casing`` but
|
|
the response data is ``CamelCased`` then you will need to manually convert
|
|
all the response elements back to ``snake_case`` in order to properly
|
|
round trip.
|
|
|
|
This makes the case for having consistent casing for both input and
|
|
output. Why not use ``snake_casing`` for input as well as output?
|
|
|
|
We choose to use ``CamelCasing`` because this is the casing used by
|
|
AWS services. As a result, we don't have to do any translation from
|
|
``CamelCasing`` to ``snake_casing``. We can use the response values
|
|
exactly as they are returned from AWS services.
|
|
|
|
This also means that if you are reading the AWS API documentation
|
|
for services, the names and casing referenced there will match
|
|
what you would provide to botocore. For example, here's the
|
|
corresponding API documentation for
|
|
`dynamodb.describe_table
|
|
<http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html>`__.
|