.. versionchanged:: 2018.3.0
        The repository and tag must now be passed separately using the
        ``repository`` and ``tag`` arguments, rather than together in the (now
        deprecated) ``image`` argument.

    Imports content from a local tarball or a URL as a new docker image

    source
        Content to import (URL or absolute path to a tarball).  URL can be a
        file on the Salt fileserver (i.e.
        ``salt://path/to/rootfs/tarball.tar.xz``. To import a file from a
        saltenv other than ``base`` (e.g. ``dev``), pass it at the end of the
        URL (ex. ``salt://path/to/rootfs/tarball.tar.xz?saltenv=dev``).

    repository
        Repository name for the image being imported

        .. versionadded:: 2018.3.0

    tag : latest
        Tag name for the image

        .. versionadded:: 2018.3.0

    image
        .. deprecated:: 2018.3.0
            Use both ``repository`` and ``tag`` instead

    api_response : False
        If ``True`` an ``api_response`` key will be present in the return data,
        containing the raw output from the Docker API.


    **RETURN DATA**

    A dictionary containing the following keys:

    - ``Id`` - ID of the newly-created image
    - ``Image`` - Name of the newly-created image
    - ``Time_Elapsed`` - Time in seconds taken to perform the commit


    CLI Example:

    .. code-block:: bash

        salt myminion docker.import /tmp/cent7-minimal.tar.xz myuser/centos
        salt myminion docker.import /tmp/cent7-minimal.tar.xz myuser/centos:7
        salt myminion docker.import salt://dockerimages/cent7-minimal.tar.xz myuser/centos:7

def import_(source,
            repository,
            tag='latest',
            api_response=False):
    '''
    .. versionchanged:: 2018.3.0
        The repository and tag must now be passed separately using the
        ``repository`` and ``tag`` arguments, rather than together in the (now
        deprecated) ``image`` argument.

    Imports content from a local tarball or a URL as a new docker image

    source
        Content to import (URL or absolute path to a tarball).  URL can be a
        file on the Salt fileserver (i.e.
        ``salt://path/to/rootfs/tarball.tar.xz``. To import a file from a
        saltenv other than ``base`` (e.g. ``dev``), pass it at the end of the
        URL (ex. ``salt://path/to/rootfs/tarball.tar.xz?saltenv=dev``).

    repository
        Repository name for the image being imported

        .. versionadded:: 2018.3.0

    tag : latest
        Tag name for the image

        .. versionadded:: 2018.3.0

    image
        .. deprecated:: 2018.3.0
            Use both ``repository`` and ``tag`` instead

    api_response : False
        If ``True`` an ``api_response`` key will be present in the return data,
        containing the raw output from the Docker API.


    **RETURN DATA**

    A dictionary containing the following keys:

    - ``Id`` - ID of the newly-created image
    - ``Image`` - Name of the newly-created image
    - ``Time_Elapsed`` - Time in seconds taken to perform the commit


    CLI Example:

    .. code-block:: bash

        salt myminion docker.import /tmp/cent7-minimal.tar.xz myuser/centos
        salt myminion docker.import /tmp/cent7-minimal.tar.xz myuser/centos:7
        salt myminion docker.import salt://dockerimages/cent7-minimal.tar.xz myuser/centos:7
    '''
    if not isinstance(repository, six.string_types):
        repository = six.text_type(repository)
    if not isinstance(tag, six.string_types):
        tag = six.text_type(tag)

    path = __salt__['container_resource.cache_file'](source)

    time_started = time.time()
    response = _client_wrapper('import_image',
                               path,
                               repository=repository,
                               tag=tag)
    ret = {'Time_Elapsed': time.time() - time_started}
    _clear_context()

    if not response:
        raise CommandExecutionError(
            'Import failed for {0}, no response returned from Docker API'
            .format(source)
        )
    elif api_response:
        ret['API_Response'] = response

    errors = []
    # Iterate through API response and collect information
    for item in response:
        try:
            item_type = next(iter(item))
        except StopIteration:
            continue
        if item_type == 'status':
            _import_status(ret, item, repository, tag)
        elif item_type == 'errorDetail':
            _error_detail(errors, item)

    if 'Id' not in ret:
        # API returned information, but there was no confirmation of a
        # successful push.
        msg = 'Import failed for {0}'.format(source)
        if errors:
            msg += '. Error(s) follow:\n\n{0}'.format(
                '\n\n'.join(errors)
            )
        raise CommandExecutionError(msg)

    return ret