(
    compose_file=None,
    build=False,
    service_name=None,
    up=None,
    down=None,
    on_error=None,
    sleep=None,
    endpoints=None,
    log_patterns=None,
    mount_logs=False,
    conditions=None,
    env_vars=None,
    wrappers=None,
    attempts=None,
    attempts_wait=1,
)
A convenient context manager for safely setting up and tearing down Docker environments.

    - **compose_file** (_str_) - A path to a Docker compose file. A custom tear
      down is not required when using this.
    - **build** (_bool_) - Whether or not to build images for when `compose_file` is provided
    - **service_name** (_str_) - Optional name for when ``compose_file`` is provided
    - **up** (_callable_) - A custom setup callable
    - **down** (_callable_) - A custom tear down callable. This is required when using a custom setup.
    - **on_error** (_callable_) - A callable called in case of an unhandled exception
    - **sleep** (_float_) - Number of seconds to wait before yielding. This occurs after all conditions are successful.
    - **endpoints** (_List[str]_) - Endpoints to verify access for before yielding. Shorthand for adding
      `CheckEndpoints(endpoints)` to the `conditions` argument.
    - **log_patterns** (_List[str|re.Pattern]_) - Regular expression patterns to find in Docker logs before yielding.
      This is only available when `compose_file` is provided. Shorthand for adding
      `CheckDockerLogs(compose_file, log_patterns)` to the `conditions` argument.
    - **mount_logs** (_bool_) - Whether or not to mount log files in Agent containers based on example logs
      configuration
    - **conditions** (_callable_) - A list of callable objects that will be executed before yielding to
      check for errors
    - **env_vars** (_dict_) - A dictionary to update `os.environ` with during execution
    - **wrappers** (_List[callable]_) - A list of context managers to use during execution
    - **attempts** (_int_) - Number of attempts to run `up` successfully
    - **attempts_wait** (_int_) - Time to wait between attempts
A convenient context manager for safely setting up and tearing down Docker environments.
A convenient context manager for safely setting up and tearing down Docker environments .
def docker_run(
    compose_file=None,
    build=False,
    service_name=None,
    up=None,
    down=None,
    on_error=None,
    sleep=None,
    endpoints=None,
    log_patterns=None,
    mount_logs=False,
    conditions=None,
    env_vars=None,
    wrappers=None,
    attempts=None,
    attempts_wait=1,
):
    """
    A convenient context manager for safely setting up and tearing down Docker environments.

    - **compose_file** (_str_) - A path to a Docker compose file. A custom tear
      down is not required when using this.
    - **build** (_bool_) - Whether or not to build images for when `compose_file` is provided
    - **service_name** (_str_) - Optional name for when ``compose_file`` is provided
    - **up** (_callable_) - A custom setup callable
    - **down** (_callable_) - A custom tear down callable. This is required when using a custom setup.
    - **on_error** (_callable_) - A callable called in case of an unhandled exception
    - **sleep** (_float_) - Number of seconds to wait before yielding. This occurs after all conditions are successful.
    - **endpoints** (_List[str]_) - Endpoints to verify access for before yielding. Shorthand for adding
      `CheckEndpoints(endpoints)` to the `conditions` argument.
    - **log_patterns** (_List[str|re.Pattern]_) - Regular expression patterns to find in Docker logs before yielding.
      This is only available when `compose_file` is provided. Shorthand for adding
      `CheckDockerLogs(compose_file, log_patterns)` to the `conditions` argument.
    - **mount_logs** (_bool_) - Whether or not to mount log files in Agent containers based on example logs
      configuration
    - **conditions** (_callable_) - A list of callable objects that will be executed before yielding to
      check for errors
    - **env_vars** (_dict_) - A dictionary to update `os.environ` with during execution
    - **wrappers** (_List[callable]_) - A list of context managers to use during execution
    - **attempts** (_int_) - Number of attempts to run `up` successfully
    - **attempts_wait** (_int_) - Time to wait between attempts
    """
    if compose_file and up:
        raise TypeError('You must select either a compose file or a custom setup callable, not both.')

    if compose_file is not None:
        if not isinstance(compose_file, string_types):
            raise TypeError('The path to the compose file is not a string: {}'.format(repr(compose_file)))

        set_up = ComposeFileUp(compose_file, build=build, service_name=service_name)
        if down is not None:
            tear_down = down
        else:
            tear_down = ComposeFileDown(compose_file)
        if on_error is None:
            on_error = ComposeFileLogs(compose_file)
    else:
        set_up = up
        tear_down = down

    if attempts is not None:
        saved_set_up = set_up

        @retry(wait=wait_fixed(attempts_wait), stop=stop_after_attempt(attempts))
        def set_up_with_retry():
            return saved_set_up()

        set_up = set_up_with_retry

    docker_conditions = []

    if log_patterns is not None:
        if compose_file is None:
            raise ValueError(
                'The `log_patterns` convenience is unavailable when using '
                'a custom setup. Please use a custom condition instead.'
            )
        docker_conditions.append(CheckDockerLogs(compose_file, log_patterns))

    if conditions is not None:
        docker_conditions.extend(conditions)

    wrappers = list(wrappers) if wrappers is not None else []

    if mount_logs:
        if isinstance(mount_logs, dict):
            wrappers.append(shared_logs(mount_logs['logs']))
        # Easy mode, read example config
        else:
            # An extra level deep because of the context manager
            check_root = find_check_root(depth=2)

            example_log_configs = _read_example_logs_config(check_root)
            if mount_logs is True:
                wrappers.append(shared_logs(example_log_configs))
            elif isinstance(mount_logs, (list, set)):
                wrappers.append(shared_logs(example_log_configs, mount_whitelist=mount_logs))
            else:
                raise TypeError(
                    'mount_logs: expected True, a list or a set, but got {}'.format(type(mount_logs).__name__)
                )

    with environment_run(
        up=set_up,
        down=tear_down,
        on_error=on_error,
        sleep=sleep,
        endpoints=endpoints,
        conditions=docker_conditions,
        env_vars=env_vars,
        wrappers=wrappers,
    ) as result:
        yield result
def docker_run ( compose_file = None , build = False , service_name = None , up = None , down = None , on_error = None , sleep = None , endpoints = None , log_patterns = None , mount_logs = False , conditions = None , env_vars = None , wrappers = None , attempts = None , attempts_wait = 1 , ) : if compose_file and up : raise TypeError ( 'You must select either a compose file or a custom setup callable, not both.' ) if compose_file is not None : if not isinstance ( compose_file , string_types ) : raise TypeError ( 'The path to the compose file is not a string: {}' . format ( repr ( compose_file ) ) ) set_up = ComposeFileUp ( compose_file , build = build , service_name = service_name ) if down is not None : tear_down = down else : tear_down = ComposeFileDown ( compose_file ) if on_error is None : on_error = ComposeFileLogs ( compose_file ) else : set_up = up tear_down = down if attempts is not None : saved_set_up = set_up @ retry ( wait = wait_fixed ( attempts_wait ) , stop = stop_after_attempt ( attempts ) ) def set_up_with_retry ( ) : return saved_set_up ( ) set_up = set_up_with_retry docker_conditions = [ ] if log_patterns is not None : if compose_file is None : raise ValueError ( 'The `log_patterns` convenience is unavailable when using ' 'a custom setup. Please use a custom condition instead.' ) docker_conditions . append ( CheckDockerLogs ( compose_file , log_patterns ) ) if conditions is not None : docker_conditions . extend ( conditions ) wrappers = list ( wrappers ) if wrappers is not None else [ ] if mount_logs : if isinstance ( mount_logs , dict ) : wrappers . append ( shared_logs ( mount_logs [ 'logs' ] ) ) # Easy mode, read example config else : # An extra level deep because of the context manager check_root = find_check_root ( depth = 2 ) example_log_configs = _read_example_logs_config ( check_root ) if mount_logs is True : wrappers . append ( shared_logs ( example_log_configs ) ) elif isinstance ( mount_logs , ( list , set ) ) : wrappers . append ( shared_logs ( example_log_configs , mount_whitelist = mount_logs ) ) else : raise TypeError ( 'mount_logs: expected True, a list or a set, but got {}' . format ( type ( mount_logs ) . __name__ ) ) with environment_run ( up = set_up , down = tear_down , on_error = on_error , sleep = sleep , endpoints = endpoints , conditions = docker_conditions , env_vars = env_vars , wrappers = wrappers , ) as result : yield result