## Service Clients Usage

updated: December 08, 2017

# Service Clients Usage

Tests make requests against APIs using service clients. Service clients are specializations of the `RestClient` class. The service clients that cover the APIs exposed by a service should be grouped in a service clients module. A service clients module is python module where all service clients are defined. If major API versions are available, submodules should be defined, one for each version.

The `ClientsFactory` class helps initializing all clients of a specific service client module from a set of shared parameters.

The `ServiceClients` class provides a convenient way to get access to all available service clients initialized with a provided set of credentials.

## The clients management module

class `ClientsFactory`(module_path, client_names, auth_provider, **kwargs)

  Builds service clients for a service client module

  This class implements the logic of feeding service client parameters to service clients from a specific module. It allows setting the parameters once and obtaining new instances of the clients without the need of passing any parameter.

  ClientsFactory can be used directly, or consumed via the ServiceClients class, which manages the authorization part.

class `ServiceClients`(credentials, identity_uri, region=None, scope='project', disable_ssl_certificate_validation=True, ca_certs=None, trace_requests='', client_parameters=None, proxy_url=None)

  Service client provider class

  The ServiceClients object provides a useful means for tests to access service clients configured for a specified set of credentials. It hides some of the complexity from the authorization and configuration layers.

  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()

  `register_service_client_module`(name, service_version, module_path, client_names, **kwargs)

    Register a service client module

    Initiates a client factory for the specified module, using this class auth_provider, and accessible via a name attribute in the service client.

    Parameters:

    - name – Name used to access the client
    - service_version – Name of the service complete with version. Used to track registered services. When a plugin implements it, it can be used by other plugins to obtain their configuration.
    - module_path – Path to module that includes all service clients. All service client classes must be exposed by a single module. If they are separated in different modules, defining __all__ in the root module can help, similar to what is done by service clients in tempest.
    - client_names – List or set of names of service client classes.
    - kwargs – Extra optional parameters to be passed to all clients. ServiceClient provides defaults for region, dscv, ca_certs, http proxies and trace_requests.

    Raises:

    - ServiceClientRegistrationException – if the provided name is already in use or if service_version is already registered.
    - ImportError – if module_path cannot be imported.

`available_modules`()

  Set of service client modules available in Tempest and plugins

  Set of stable service clients from Tempest and service clients exposed by plugins. This set of available modules can be used for automatic configuration.

  Raises: | PluginRegistrationException – if a plugin exposes a service_version already defined by Tempest or another plugin.

  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)

`tempest_modules`()

  Dict of service client modules available in Tempest.

  Provides a dict of stable service modules available in Tempest, with `service_version` as key, and the module object as value.

## Compute service client modules

- Compute Client Usage

updated: December 08, 2017

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug questions?