=======================================
Use python-tempestconf as Python module
=======================================

`python-tempestconf` can be imported and used from a different Python project.

.. warning::

    The import of config_tempest is possible only when the tool is installed
    from **master branch** or via pip, however, **python-tempestconf-2.0.0.
    or newer has to be installed**.

Installation
++++++++++++

See our `Install Guide`_ on how to install `python-tempestconf`.

.. _Install Guide: ../install/installation.html

Import
++++++

Import python-tempestconf in your project as follows:

.. code-block:: Python

    from config_tempest import main as tempestconf

python-tempestconf needs cloud credentials in order to create a tempest
configuration file. There is a helper method for obtaining cloud credentials
which uses
`os-client-config <https://docs.openstack.org/os-client-config/latest/user/configuration.html>`_
for parsing the cloud for credentials.

The following example shows how to get cloud credentials and how to pass it to
the configuration tool:

.. code-block:: Python

    # The following call will return a dict containing cloud credentials,
    # for example:
    # >>> tempestconf.get_cloud_creds(args_namespace)
    # {
    #     'username': 'demo',
    #     'project_name': 'demo',
    #     'user_domain_name': 'Default',
    #     'auth_url': 'http://172.16.52.8:5000/v3',
    #     'password': 'f0921edc3c2b4fc8',
    #     'project_domain_name': 'Default'
    # }
    cloud_creds = tempestconf.get_cloud_creds(args_namespace)

    # Then the configuration step can be run using:
    tempestconf.config_tempest(cloud_creds=cloud_creds)

.. note::

    If `args_namespace` contains **--os-cloud** argument, the `get_cloud_creds`
    method returns cloud credentials related to that cloud, otherwise, returns
    credentials of the current cloud (according to the sourced credentials).


List of arguments which may be passed to `config_tempest`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++

 * cloud_creds
 * create
 * create_accounts_file
 * debug
 * deployer_input
 * image_disk_format
 * image_path
 * network_id
 * non_admin
 * os_cloud
 * out
 * overrides
 * remove
 * test_accounts
 * verbose

.. note::

    For detailed description of the options see our `CLI documentation`_

    .. _CLI documentation: ../cli/cli_options.html


Example implementation
++++++++++++++++++++++

1. Save following code snippet as `example.py`:

    .. code-block:: Python

        import argparse
        from config_tempest import main as tempestconf

        parser = argparse.ArgumentParser(description='Example implementation.')
        args = parser.parse_args()

        # gets credentials of the current cloud according to
        # the sourced credentials
        cloud_creds = tempestconf.get_cloud_creds(args)

        tempestconf.config_tempest(non_admin=True,
                                   out='./etc/tempest.conf',
                                   cloud_creds=cloud_creds)

2. Source your OpenStack RC file containing the cloud credentials. Let's say
   you have a overcloud_rc file with the following content:

    .. code-block:: Bash

        $ cat overcloud_rc
        unset OS_SERVICE_TOKEN
        export OS_USERNAME=demo
        export OS_PASSWORD='password'
        export OS_AUTH_URL=http://172.16.52.15/identity/v3
        export PS1='[\u@\h \W(keystone_demo)]\$ '
        export OS_PROJECT_NAME=demo
        export OS_USER_DOMAIN_NAME=default
        export OS_PROJECT_DOMAIN_NAME=default
        export OS_IDENTITY_API_VERSION=3

   Then it can be source by:

    .. code-block:: Bash

        $ source overcloud_rc


3. Run the `example.py`:

    .. code-block:: Bash

        $ python example.py


Example implementation with a named cloud
+++++++++++++++++++++++++++++++++++++++++

1. Let's say there is a `clouds.yaml` file located in `/etc/openstack/` with
   the following content:

    .. code-block:: Bash

        $ cat /etc/openstack/clouds.yaml
        clouds:
          devstack:
            auth:
              auth_url: http://172.16.52.15/identity/v3
              password: password
              project_domain_id: default
              project_name: demo
              user_domain_id: default
              username: demo
            identity_api_version: '3'
            region_name: RegionOne
            volume_api_version: '2'


2. Save following code snippet as an `example.py`:

    .. code-block:: Python

        import argparse
        from config_tempest import main as tempestconf

        parser = argparse.ArgumentParser(description='Example implementation.')
        # Let's add an os_cloud option which will be passed
        # to config_tempest later.
        parser.add_argument('--os-cloud', help='Name of a named cloud.')
        args = parser.parse_args()

        # gets credentials to the devstack cloud
        cloud_creds = tempestconf.get_cloud_creds(args)

        tempestconf.config_tempest(non_admin=True,
                                   out='./etc/tempest.conf',
                                   cloud_creds=cloud_creds)

3. Run the `example.py`:

    .. code-block:: Bash

        $ python example.py --os-cloud devstack

    .. note::

        In this example you **don't need** to source cloud credentials. The
        credentials are obtained from the `/etc/openstack/clouds.yaml`
        thanks to `--os-cloud` argument.
