Improve docstring examples

This commit improves docstring examples. The original examples are
written in interactive mode style. However, I feel it's weird when it is
multiple lines, especially. So, this commit just removes '>>> ' and
updates some code block attributes.

Change-Id: I2f46042607c0f57d93634fbdffbb4400256a8489
This commit is contained in:
Masayuki Igawa 2017-04-11 16:06:46 +09:00
parent 9d52e99ef1
commit 683abe2a39
No known key found for this signature in database
GPG Key ID: 251CCDE9053850E4
2 changed files with 101 additions and 97 deletions

View File

@ -72,15 +72,15 @@ def available_modules():
:raise PluginRegistrationException: if a plugin exposes a service_version
already defined by Tempest or another plugin.
Examples:
Examples::
>>> from tempest import config
>>> params = {}
>>> for service_version in available_modules():
>>> service = service_version.split('.')[0]
>>> params[service] = config.service_client_config(service)
>>> service_clients = ServiceClients(creds, identity_uri,
>>> client_parameters=params)
from tempest import config
params = {}
for service_version in available_modules():
service = service_version.split('.')[0]
params[service] = config.service_client_config(service)
service_clients = ServiceClients(creds, identity_uri,
client_parameters=params)
"""
extra_service_versions = set([])
_tempest_modules = set(tempest_modules())
@ -163,17 +163,17 @@ class ClientsFactory(object):
parameters cannot be deleted.
:raise ImportError if the specified module_path cannot be imported
Example:
Example::
>>> # Get credentials and an auth_provider
>>> clients = ClientsFactory(
>>> module_path='my_service.my_service_clients',
>>> client_names=['ServiceClient1', 'ServiceClient2'],
>>> auth_provider=auth_provider,
>>> service='my_service',
>>> region='region1')
>>> my_api_client = clients.MyApiClient()
>>> my_api_client_region2 = clients.MyApiClient(region='region2')
# Get credentials and an auth_provider
clients = ClientsFactory(
module_path='my_service.my_service_clients',
client_names=['ServiceClient1', 'ServiceClient2'],
auth_provider=auth_provider,
service='my_service',
region='region1')
my_api_client = clients.MyApiClient()
my_api_client_region2 = clients.MyApiClient(region='region2')
"""
# Import the module. If it's not importable, the raised exception
@ -244,19 +244,19 @@ class ServiceClients(object):
It hides some of the complexity from the authorization and configuration
layers.
Examples:
Examples::
>>> # johndoe is a tempest.lib.auth.Credentials type instance
>>> johndoe_clients = clients.ServiceClients(johndoe, identity_uri)
>>>
>>> # List servers in default region
>>> johndoe_servers_client = johndoe_clients.compute.ServersClient()
>>> johndoe_servers = johndoe_servers_client.list_servers()
>>>
>>> # List servers in Region B
>>> johndoe_servers_client_B = johndoe_clients.compute.ServersClient(
>>> region='B')
>>> johndoe_servers = johndoe_servers_client_B.list_servers()
# johndoe is a tempest.lib.auth.Credentials type instance
johndoe_clients = clients.ServiceClients(johndoe, identity_uri)
# List servers in default region
johndoe_servers_client = johndoe_clients.compute.ServersClient()
johndoe_servers = johndoe_servers_client.list_servers()
# List servers in Region B
johndoe_servers_client_B = johndoe_clients.compute.ServersClient(
region='B')
johndoe_servers = johndoe_servers_client_B.list_servers()
"""
# NOTE(andreaf) This class does not depend on tempest configuration
@ -305,14 +305,14 @@ class ServiceClients(object):
Registry automatically for all service client (Tempest stable ones
and plugins).
Examples:
Examples::
>>> identity_params = config.service_client_config('identity')
>>> params = {
>>> 'identity': identity_params,
>>> 'compute': {'region': 'region2'}}
>>> manager = lib_manager.Manager(
>>> my_creds, identity_uri, client_parameters=params)
identity_params = config.service_client_config('identity')
params = {
'identity': identity_params,
'compute': {'region': 'region2'}}
manager = lib_manager.Manager(
my_creds, identity_uri, client_parameters=params)
:param credentials: An instance of `auth.Credentials`
:param identity_uri: URI of the identity API. This should be a
@ -328,7 +328,6 @@ class ServiceClients(object):
name, as declared in `service_clients.available_modules()` except
for the version. Values are dictionaries of parameters that are
going to be passed to all clients in the service client module.
"""
self._registered_services = set([])
self.credentials = credentials

View File

@ -51,36 +51,37 @@ class TempestPlugin(object):
:param ConfigOpts conf: The conf object that can be used to register
additional options on.
Example:
>>> # Config options are defined in a config.py module
>>> service_option = cfg.BoolOpt(
>>> "my_service",
>>> default=True,
>>> help="Whether or not my service is available")
>>>
>>> # Note: as long as the group is listed in get_opt_lists,
>>> # it will be possible to access its optins in the plugin code
>>> # via ("-" in the group name are replaces with "_"):
>>> # CONF.my_service.<option_name>
>>> my_service_group = cfg.OptGroup(name="my-service",
>>> title="My service options")
>>>
>>> MyServiceGroup = [<list of options>]
>>> # (...) More groups and options...
>>>
>>> # Plugin is implemented in a plugin.py module
>>> from my_plugin import config as my_config
>>>
>>> def register_opts(self, conf):
>>> conf.register_opt(my_config.service_option,
>>> group='service_available')
>>> conf.register_group(my_config.my_service_group)
>>> conf.register_opts(my_config.MyService +
>>> my_config.my_service_group)
>>>
>>> conf.register_group(my_config.my_service_feature_group)
>>> conf.register_opts(my_config.MyServiceFeaturesGroup,
>>> my_config.my_service_feature_group)
Example::
# Config options are defined in a config.py module
service_option = cfg.BoolOpt(
"my_service",
default=True,
help="Whether or not my service is available")
# Note: as long as the group is listed in get_opt_lists,
# it will be possible to access its optins in the plugin code
# via ("-" in the group name are replaces with "_"):
# CONF.my_service.<option_name>
my_service_group = cfg.OptGroup(name="my-service",
title="My service options")
MyServiceGroup = [<list of options>]
# (...) More groups and options...
# Plugin is implemented in a plugin.py module
from my_plugin import config as my_config
def register_opts(self, conf):
conf.register_opt(my_config.service_option,
group='service_available')
conf.register_group(my_config.my_service_group)
conf.register_opts(my_config.MyService +
my_config.my_service_group)
conf.register_group(my_config.my_service_feature_group)
conf.register_opts(my_config.MyServiceFeaturesGroup,
my_config.my_service_feature_group)
"""
return
@ -107,37 +108,41 @@ class TempestPlugin(object):
of `service_clients.ServiceClients.register_service_client_module`.
:rtype: list of dictionaries
Example:
Example implementation with one service client::
>>> # Example implementation with one service client
>>> myservice_config = config.service_client_config('myservice')
>>> params = {
>>> 'name': 'myservice',
>>> 'service_version': 'myservice',
>>> 'module_path': 'myservice_tempest_tests.services',
>>> 'client_names': ['API1Client', 'API2Client'],
>>> }
>>> params.update(myservice_config)
>>> return [params]
def get_service_clients(self):
# Example implementation with one service client
myservice_config = config.service_client_config('myservice')
params = {
'name': 'myservice',
'service_version': 'myservice',
'module_path': 'myservice_tempest_tests.services',
'client_names': ['API1Client', 'API2Client'],
}
params.update(myservice_config)
return [params]
>>> # Example implementation with two service clients
>>> foo1_config = config.service_client_config('foo')
>>> params_foo1 = {
>>> 'name': 'foo_v1',
>>> 'service_version': 'foo.v1',
>>> 'module_path': 'bar_tempest_tests.services.foo.v1',
>>> 'client_names': ['API1Client', 'API2Client'],
>>> }
>>> params_foo1.update(foo_config)
>>> foo2_config = config.service_client_config('foo')
>>> params_foo2 = {
>>> 'name': 'foo_v2',
>>> 'service_version': 'foo.v2',
>>> 'module_path': 'bar_tempest_tests.services.foo.v2',
>>> 'client_names': ['API1Client', 'API2Client'],
>>> }
>>> params_foo2.update(foo2_config)
>>> return [params_foo1, params_foo2]
Example implementation with two service clients::
def get_service_clients(self):
# Example implementation with two service clients
foo1_config = config.service_client_config('foo')
params_foo1 = {
'name': 'foo_v1',
'service_version': 'foo.v1',
'module_path': 'bar_tempest_tests.services.foo.v1',
'client_names': ['API1Client', 'API2Client'],
}
params_foo1.update(foo_config)
foo2_config = config.service_client_config('foo')
params_foo2 = {
'name': 'foo_v2',
'service_version': 'foo.v2',
'module_path': 'bar_tempest_tests.services.foo.v2',
'client_names': ['API1Client', 'API2Client'],
}
params_foo2.update(foo2_config)
return [params_foo1, params_foo2]
"""
return []