Sitelet https://github.com/devinshields/aws-cli/commit/620530ca113c3c09f8b1aaac52ae93f3c133e394
Skip to content

Commit 620530c

Browse files
jameslsjamesls
committed
Document supported config file variables
This includes the newly added metadata_service_timeout and metadata_service_num_attempts. As part of this change, I've added the ability for custom commands to provide their description/synopsis/examples in rst files. That way the classes for commands do not have to include the documentation text as part of the class definition.
1 parent ecb882b commit 620530c

4 files changed

Lines changed: 85 additions & 19 deletions

File tree

‎awscli/customizations/commands.py‎

Lines changed: 45 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1-
import bcdoc.docevents
1+
import os
22

3+
import bcdoc.docevents
34
from botocore.compat import OrderedDict
45

6+
import awscli
57
from awscli.clidocs import CLIDocumentEventHandler
68
from awscli.argparser import ArgTableArgParser
79
from awscli.clidriver import CLICommand
@@ -55,6 +57,22 @@ class BasicCommand(CLICommand):
5557
# The command_class must subclass from ``BasicCommand``.
5658
SUBCOMMANDS = []
5759

60+
FROM_FILE = object()
61+
# You can set the DESCRIPTION, SYNOPSIS, and EXAMPLES to FROM_FILE
62+
# and we'll automatically read in that data from the file.
63+
# This is useful if you have a lot of content and would prefer to keep
64+
# the docs out of the class definition. For example:
65+
#
66+
# DESCRIPTION = FROM_FILE
67+
#
68+
# will set the DESCRIPTION value to the contents of
69+
# awscli/examples/<command name>/_description.rst
70+
# The naming conventions for these attributes are:
71+
#
72+
# DESCRIPTION = awscli/examples/<command name>/_description.rst
73+
# SYNOPSIS = awscli/examples/<command name>/_synopsis.rst
74+
# EXAMPLES = awscli/examples/<command name>/_examples.rst
75+
5876
# At this point, the only other thing you have to implement is a _run_main
5977
# method (see the method for more information).
6078

@@ -135,14 +153,37 @@ def __init__(self, session, command_object, command_table, arg_table,
135153

136154
# These are public attributes that are mapped from the command
137155
# object. These are used by the BasicDocHandler below.
138-
self.description = command_object.DESCRIPTION
139-
self.synopsis = command_object.SYNOPSIS
140-
self.examples = command_object.EXAMPLES
156+
self._description = command_object.DESCRIPTION
157+
self._synopsis = command_object.SYNOPSIS
158+
self._examples = command_object.EXAMPLES
141159

142160
@property
143161
def name(self):
144162
return self.obj.NAME
145163

164+
@property
165+
def description(self):
166+
return self._get_doc_contents('_description')
167+
168+
@property
169+
def synopsis(self):
170+
return self._get_doc_contents('_synopsis')
171+
172+
@property
173+
def examples(self):
174+
return self._get_doc_contents('_examples')
175+
176+
def _get_doc_contents(self, attr_name):
177+
value = getattr(self, attr_name)
178+
if value is BasicCommand.FROM_FILE:
179+
doc_path = os.path.join(
180+
os.path.abspath(os.path.dirname(awscli.__file__)), 'examples',
181+
self.name, attr_name + '.rst')
182+
with open(doc_path) as f:
183+
return f.read()
184+
else:
185+
return value
186+
146187
def __call__(self, args, parsed_globals):
147188
# Create an event handler for a Provider Document
148189
instance = self.EventHandlerClass(self)

‎awscli/customizations/configure.py‎

Lines changed: 1 addition & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -273,21 +273,7 @@ def _lookup_config(self, name):
273273

274274
class ConfigureCommand(BasicCommand):
275275
NAME = 'configure'
276-
DESCRIPTION = (
277-
'Configure AWS CLI configuration data. If this command '
278-
'is run with no arguments, you will be prompted for configuration '
279-
'values such as your AWS Access Key Id and you AWS Secret Access '
280-
'Key. You can configure a specific profile using the ``--profile`` '
281-
'argument. If your config file does not exist (the default location '
282-
'is ``~/.aws/config``), it will be automatically created for you. '
283-
'To keep an existing value, hit enter when prompted for the value.\n\n'
284-
'When you are prompted for information, the current value will be '
285-
'displayed in ``[brackets]``. If the config item has no value, it '
286-
'be displayed as ``[None]``.\n\n'
287-
'Note that the ``configure`` command only work with values from the '
288-
'config file. It does not use any configuration values from '
289-
'environment variables or the IAM role.\n'
290-
)
276+
DESCRIPTION = BasicCommand.FROM_FILE
291277
SYNOPSIS = ('aws configure [--profile profile-name]')
292278
EXAMPLES = (
293279
'To create a new configuration::\n'

‎awscli/examples/configure/_description.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
Configure AWS CLI configuration data. If this command is run with no
2+
arguments, you will be prompted for configuration values such as your AWS
3+
Access Key Id and you AWS Secret Access Key. You can configure a specific
4+
profile using the ``--profile`` argument. If your config file does not exist
5+
(the default location is ``~/.aws/config``), it will be automatically created
6+
for you. To keep an existing value, hit enter when prompted for the value.
7+
When you are prompted for information, the current value will be displayed in
8+
``[brackets]``. If the config item has no value, it be displayed as
9+
``[None]``. Note that the ``configure`` command only work with values from the
10+
config file. It does not use any configuration values from environment
11+
variables or the IAM role.
12+
13+
=======================
14+
Configuration Variables
15+
=======================
16+
17+
The following configuration variables are supported in the config file:
18+
19+
* **aws_access_key_id** - The AWS access key part of your credentials
20+
* **aws_secret_access_key** - The AWS secret access key part of your credentials
21+
* **aws_security_token** - The security token part of your credentials (session tokens only)
22+
* **metadata_service_timeout** - The number of seconds to wait until the metadata service
23+
request times out. This is used if you are using an IAM role to provide
24+
your credentials.
25+
* **metadata_service_num_attempts** - The number of attempts to try to retrieve
26+
credentials. If you know for certain you will be using an IAM role on an
27+
Amazon EC2 instance, you can set this value to ensure any intermittent
28+
failures are retried. By default this value is 1.

‎tests/unit/docs/test_help_output.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -262,3 +262,14 @@ def test_create_image_renames(self):
262262
self.driver.main(['ec2', 'create-image', 'help'])
263263
self.assert_not_contains('no-no-reboot')
264264
self.assert_contains('--reboot')
265+
266+
class TestCustomCommandDocsFromFile(BaseAWSHelpOutputTest):
267+
def test_description_from_rst_file(self):
268+
# The description for the configure command
269+
# is in _description.rst. We're verifying that we
270+
# can read those contents properly.
271+
self.driver.main(['configure', 'help'])
272+
# These are a few options that are documented in the help output.
273+
self.assert_contains('metadata_service_timeout')
274+
self.assert_contains('metadata_service_num_attempts')
275+
self.assert_contains('aws_access_key_id')

0 commit comments

Comments
 (0)