Instruction:
Can you generate the documentation for the following Python 3 function
def _read(self, mux, gain, data_rate, mode):
        config = ADS1x15_CONFIG_OS_SINGLE  # Go out of power-down mode for conversion.
        # Specify mux value.
        config |= (mux & 0x07) << ADS1x15_CONFIG_MUX_OFFSET
        # Validate the passed in gain and then set it in the config.
        if gain not in ADS1x15_CONFIG_GAIN:
            raise ValueError('Gain must be one of: 2/3, 1, 2, 4, 8, 16')
        config |= ADS1x15_CONFIG_GAIN[gain]
        # Set the mode (continuous or single shot).
        config |= mode
        # Get the default data rate if none is specified (default differs between
        # ADS1015 and ADS1115).
        if data_rate is None:
            data_rate = self._data_rate_default()
        # Set the data rate (this is controlled by the subclass as it differs
        # between ADS1015 and ADS1115).
        config |= self._data_rate_config(data_rate)
        config |= ADS1x15_CONFIG_COMP_QUE_DISABLE  # Disble comparator mode.
        # Send the config value to start the ADC conversion.
        # Explicitly break the 16-bit value down to a big endian pair of bytes.
        self._device.writeList(ADS1x15_POINTER_CONFIG, [(config >> 8) & 0xFF, config & 0xFF])
        # Wait for the ADC sample to finish based on the sample rate plus a
        # small offset to be sure (0.1 millisecond).
        time.sleep(1.0/data_rate+0.0001)
        # Retrieve the result.
        result = self._device.readList(ADS1x15_POINTER_CONVERSION, 2)
        return self._conversion_value(result[1], result[0])

Response: Perform an ADC read with the provided mux gain data_rate and mode.


Instruction:
Write a Python 3 script to
perform an ADC read with the provided mux gain data_rate mode high_threshold low_threshold active_low traditional and latching enabled as specified.

Response:
def _read_comparator(self, mux, gain, data_rate, mode, high_threshold,
                         low_threshold, active_low, traditional, latching,
                         num_readings):
        """Perform an ADC read with the provided mux, gain, data_rate, and mode
        values and with the comparator enabled as specified.  Returns the signed
        integer result of the read.
        """
        assert num_readings == 1 or num_readings == 2 or num_readings == 4, 'Num readings must be 1, 2, or 4!'
        # Set high and low threshold register values.
        self._device.writeList(ADS1x15_POINTER_HIGH_THRESHOLD, [(high_threshold >> 8) & 0xFF, high_threshold & 0xFF])
        self._device.writeList(ADS1x15_POINTER_LOW_THRESHOLD, [(low_threshold >> 8) & 0xFF, low_threshold & 0xFF])
        # Now build up the appropriate config register value.
        config = ADS1x15_CONFIG_OS_SINGLE  # Go out of power-down mode for conversion.
        # Specify mux value.
        config |= (mux & 0x07) << ADS1x15_CONFIG_MUX_OFFSET
        # Validate the passed in gain and then set it in the config.
        if gain not in ADS1x15_CONFIG_GAIN:
            raise ValueError('Gain must be one of: 2/3, 1, 2, 4, 8, 16')
        config |= ADS1x15_CONFIG_GAIN[gain]
        # Set the mode (continuous or single shot).
        config |= mode
        # Get the default data rate if none is specified (default differs between
        # ADS1015 and ADS1115).
        if data_rate is None:
            data_rate = self._data_rate_default()
        # Set the data rate (this is controlled by the subclass as it differs
        # between ADS1015 and ADS1115).
        config |= self._data_rate_config(data_rate)
        # Enable window mode if required.
        if not traditional:
            config |= ADS1x15_CONFIG_COMP_WINDOW
        # Enable active high mode if required.
        if not active_low:
            config |= ADS1x15_CONFIG_COMP_ACTIVE_HIGH
        # Enable latching mode if required.
        if latching:
            config |= ADS1x15_CONFIG_COMP_LATCHING
        # Set number of comparator hits before alerting.
        config |= ADS1x15_CONFIG_COMP_QUE[num_readings]
        # Send the config value to start the ADC conversion.
        # Explicitly break the 16-bit value down to a big endian pair of bytes.
        self._device.writeList(ADS1x15_POINTER_CONFIG, [(config >> 8) & 0xFF, config & 0xFF])
        # Wait for the ADC sample to finish based on the sample rate plus a
        # small offset to be sure (0.1 millisecond).
        time.sleep(1.0/data_rate+0.0001)
        # Retrieve the result.
        result = self._device.readList(ADS1x15_POINTER_CONVERSION, 2)
        return self._conversion_value(result[1], result[0])


Instruction:
Here you have a function in Python 3, explain what it does
def read_adc(self, channel, gain=1, data_rate=None):
        assert 0 <= channel <= 3, 'Channel must be a value within 0-3!'
        # Perform a single shot read and set the mux value to the channel plus
        # the highest bit (bit 3) set.
        return self._read(channel + 0x04, gain, data_rate, ADS1x15_CONFIG_MODE_SINGLE)

Response: Read a single ADC channel and return the result as a signed integer.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def read_adc_difference(self, differential, gain=1, data_rate=None):
        assert 0 <= differential <= 3, 'Differential must be a value within 0-3!'
        # Perform a single shot read using the provided differential value
        # as the mux value (which will enable differential mode).
        return self._read(differential, gain, data_rate, ADS1x15_CONFIG_MODE_SINGLE)

Response: Read the difference between two ADC channels and return the ADC value as a signed integer result.


Instruction:
Given the following Python 3 function, write the documentation
def start_adc_difference(self, differential, gain=1, data_rate=None):
        assert 0 <= differential <= 3, 'Differential must be a value within 0-3!'
        # Perform a single shot read using the provided differential value
        # as the mux value (which will enable differential mode).
        return self._read(differential, gain, data_rate, ADS1x15_CONFIG_MODE_CONTINUOUS)

Response: Start continuous ADC conversions between two ADC channels.


Instruction:
Implement a Python 3 function for
starting continuous ADC conversion on the specified channel.

Response:
def start_adc_comparator(self, channel, high_threshold, low_threshold,
                             gain=1, data_rate=None, active_low=True,
                             traditional=True, latching=False, num_readings=1):
        """Start continuous ADC conversions on the specified channel (0-3) with
        the comparator enabled.  When enabled the comparator to will check if
        the ADC value is within the high_threshold & low_threshold value (both
        should be signed 16-bit integers) and trigger the ALERT pin.  The
        behavior can be controlled by the following parameters:
          - active_low: Boolean that indicates if ALERT is pulled low or high
                        when active/triggered.  Default is true, active low.
          - traditional: Boolean that indicates if the comparator is in traditional
                         mode where it fires when the value is within the threshold,
                         or in window mode where it fires when the value is _outside_
                         the threshold range.  Default is true, traditional mode.
          - latching: Boolean that indicates if the alert should be held until
                      get_last_result() is called to read the value and clear
                      the alert.  Default is false, non-latching.
          - num_readings: The number of readings that match the comparator before
                          triggering the alert.  Can be 1, 2, or 4.  Default is 1.
        Will return an initial conversion result, then call the get_last_result()
        function continuously to read the most recent conversion result.  Call
        stop_adc() to stop conversions.
        """
        assert 0 <= channel <= 3, 'Channel must be a value within 0-3!'
        # Start continuous reads with comparator and set the mux value to the
        # channel plus the highest bit (bit 3) set.
        return self._read_comparator(channel + 0x04, gain, data_rate,
                                     ADS1x15_CONFIG_MODE_CONTINUOUS,
                                     high_threshold, low_threshold, active_low,
                                     traditional, latching, num_readings)


Instruction:
Can you generate the documentation for the following Python 3 function
def start_adc_difference_comparator(self, differential, high_threshold, low_threshold,
                                        gain=1, data_rate=None, active_low=True,
                                        traditional=True, latching=False, num_readings=1):
        """Start continuous ADC conversions between two channels with
        the comparator enabled.  See start_adc_difference for valid differential
        parameter values and their meaning.  When enabled the comparator to will
        check if the ADC value is within the high_threshold & low_threshold value
        (both should be signed 16-bit integers) and trigger the ALERT pin.  The
        behavior can be controlled by the following parameters:
          - active_low: Boolean that indicates if ALERT is pulled low or high
                        when active/triggered.  Default is true, active low.
          - traditional: Boolean that indicates if the comparator is in traditional
                         mode where it fires when the value is within the threshold,
                         or in window mode where it fires when the value is _outside_
                         the threshold range.  Default is true, traditional mode.
          - latching: Boolean that indicates if the alert should be held until
                      get_last_result() is called to read the value and clear
                      the alert.  Default is false, non-latching.
          - num_readings: The number of readings that match the comparator before
                          triggering the alert.  Can be 1, 2, or 4.  Default is 1.
        Will return an initial conversion result, then call the get_last_result()
        function continuously to read the most recent conversion result.  Call
        stop_adc() to stop conversions.
        """
        assert 0 <= differential <= 3, 'Differential must be a value within 0-3!'
        # Start continuous reads with comparator and set the mux value to the
        # channel plus the highest bit (bit 3) set.
        return self._read_comparator(differential, gain, data_rate,
                                     ADS1x15_CONFIG_MODE_CONTINUOUS,
                                     high_threshold, low_threshold, active_low,
                                     traditional, latching, num_readings)

Response: Start continuous ADC conversions between two channels with the specified differential ADC value high_threshold and low_threshold and trigger the ALERT pin.


Instruction:
How would you implement a function in Python 3 that
reads the last conversion result when in continuous conversion mode. Will return a signed integer value.

Response:
def get_last_result(self):
        """Read the last conversion result when in continuous conversion mode.
        Will return a signed integer value.
        """
        # Retrieve the conversion register value, convert to a signed int, and
        # return it.
        result = self._device.readList(ADS1x15_POINTER_CONVERSION, 2)
        return self._conversion_value(result[1], result[0])


Instruction:
Implement a function in Python 3 to
remove all dusty containers with Exited in their status

Response:
def remove_exited_dusty_containers():
    """Removed all dusty containers with 'Exited' in their status"""
    client = get_docker_client()
    exited_containers = get_exited_dusty_containers()
    removed_containers = []
    for container in exited_containers:
        log_to_client("Removing container {}".format(container['Names'][0]))
        try:
            client.remove_container(container['Id'], v=True)
            removed_containers.append(container)
        except Exception as e:
            log_to_client(e.message or str(e))
    return removed_containers


Instruction:
Given the following Python 3 function, write the documentation
def remove_images():
    client = get_docker_client()
    removed = _remove_dangling_images()
    dusty_images = get_dusty_images()
    all_images = client.images(all=True)
    for image in all_images:
        if set(image['RepoTags']).intersection(dusty_images):
            try:
                client.remove_image(image['Id'])
            except Exception as e:
                logging.info("Couldn't remove image {}".format(image['RepoTags']))
            else:
                log_to_client("Removed Image {}".format(image['RepoTags']))
                removed.append(image)
    return removed

Response: Removes all dangling images as well as all images referenced in a dusty spec ; forceful removal is not used


Instruction:
Create a Python 3 function for
updating the Nginx config with the given config.

Response:
def update_nginx_from_config(nginx_config):
    """Write the given config to disk as a Dusty sub-config
    in the Nginx includes directory. Then, either start nginx
    or tell it to reload its config to pick up what we've
    just written."""
    logging.info('Updating nginx with new Dusty config')
    temp_dir = tempfile.mkdtemp()
    os.mkdir(os.path.join(temp_dir, 'html'))
    _write_nginx_config(constants.NGINX_BASE_CONFIG, os.path.join(temp_dir, constants.NGINX_PRIMARY_CONFIG_NAME))
    _write_nginx_config(nginx_config['http'], os.path.join(temp_dir, constants.NGINX_HTTP_CONFIG_NAME))
    _write_nginx_config(nginx_config['stream'], os.path.join(temp_dir, constants.NGINX_STREAM_CONFIG_NAME))
    _write_nginx_config(constants.NGINX_502_PAGE_HTML, os.path.join(temp_dir, 'html', constants.NGINX_502_PAGE_NAME))
    sync_local_path_to_vm(temp_dir, constants.NGINX_CONFIG_DIR_IN_VM)


Instruction:
Make a summary of the following Python 3 code
def _compose_restart(services):

    def _restart_container(client, container):
        log_to_client('Restarting {}'.format(get_canonical_container_name(container)))
        client.restart(container['Id'], timeout=1)

    assembled_specs = get_assembled_specs()
    if services == []:
        services = [spec.name for spec in assembled_specs.get_apps_and_services()]
    logging.info('Restarting service containers from list: {}'.format(services))
    client = get_docker_client()
    for service in services:
        container = get_container_for_app_or_service(service, include_exited=True)
        if container is None:
            log_to_client('No container found for {}'.format(service))
            continue
        stopped_linked_containers = _check_stopped_linked_containers(container, assembled_specs)
        if stopped_linked_containers:
            log_to_client('No running containers {0}, which are linked to by {1}.  Cannot restart {1}'.format(
                              stopped_linked_containers, service))
        else:
            _restart_container(client, container)

Response: Restarts all containers in the current container tree.


Instruction:
Here you have a function in Python 3, explain what it does
def update_running_containers_from_spec(compose_config, recreate_containers=True):
    write_composefile(compose_config, constants.COMPOSEFILE_PATH)
    compose_up(constants.COMPOSEFILE_PATH, 'dusty', recreate_containers=recreate_containers)

Response: Takes in a Compose spec file and updates the running containers with the new config.


Instruction:
How would you implement a function in Python 3 that
resolves a short name to a local version of the object.

Response:
def resolve(cls, all_known_repos, name):
        """We require the list of all remote repo paths to be passed in
        to this because otherwise we would need to import the spec assembler
        in this module, which would give us circular imports."""
        match = None
        for repo in all_known_repos:
            if repo.remote_path == name: # user passed in a full name
                return repo
            if name == repo.short_name:
                if match is None:
                    match = repo
                else:
                    raise RuntimeError('Short repo name {} is ambiguous. It matches both {} and {}'.format(name,
                                                                                match.remote_path,
                                                                                repo.remote_path))
        if match is None:
            raise RuntimeError('Short repo name {} does not match any known repos'.format(name))
        return match


Instruction:
Explain what the following Python 3 code does
def ensure_local_repo(self):
        if os.path.exists(self.managed_path):
            logging.debug('Repo {} already exists'.format(self.remote_path))
            return

        logging.info('Initiating clone of local repo {}'.format(self.remote_path))

        repo_path_parent = parent_dir(self.managed_path)
        if not os.path.exists(repo_path_parent):
            os.makedirs(repo_path_parent)
        with git_error_handling():
            git.Repo.clone_from(self.assemble_remote_path(), self.managed_path)

Response:
Given a Dusty repo object clone the remote into Dusty s local repos
        directory if it does not already exist.


Instruction:
Write a Python 3 script for
giving a remote path pull the latest version of the local repo and update the local copy to be up to date.

Response:
def update_local_repo(self, force=False):
        """Given a remote path (e.g. github.com/gamechanger/gclib), pull the latest
        commits from master to bring the local copy up to date."""
        self.ensure_local_repo()

        logging.info('Updating local repo {}'.format(self.remote_path))

        managed_repo = git.Repo(self.managed_path)
        with git_error_handling():
            managed_repo.remote().pull('master')
            log_to_client('Updated managed copy of {}'.format(self.remote_path))
        if not self.local_is_up_to_date():
            if force:
                with git_error_handling():
                    managed_repo.git.reset('--hard', 'origin/master')
            else:
                log_to_client('WARNING: couldn\'t update {} because of local conflicts. '
                              'A container may have modified files in the repos\'s directory. '
                              'Your code generally shouldn\'t be manipulating the contents of your repo folder - '
                              'please fix this and run `dusty up`'.format(self.managed_path))


Instruction:
Can you tell what is the following Python 3 function doing
def update_local_repo_async(self, task_queue, force=False):
        self.ensure_local_repo()
        task_queue.enqueue_task(self.update_local_repo, force=force)

Response: Local repo updating suitable for asynchronous parallel execution.


Instruction:
Write a Python 3 script for
checking if a path exists in the HFS file system.

Response:
def nfs_path_exists(path):
    """
        The normal HFS file system that your mac uses does not work the same way
        as the NFS file system.  In HFS, capitalization does not matter, but in
        NFS it does. This function checks if a folder exists in HFS file system
        using NFS semantics (case sensitive)
    """
    split_path = path.lstrip('/').split('/')
    recreated_path = '/'
    for path_element in split_path:
        if path_element not in os.listdir(recreated_path):
            return False
        recreated_path = "{}{}/".format(recreated_path, path_element)
    return True


Instruction:
Can you create a Python 3 function that
updates the Dusty - managed repos to bring it up to date with the latest master.

Response:
def update_managed_repos(force=False):
    """For any active, managed repos, update the Dusty-managed
    copy to bring it up to date with the latest master."""
    log_to_client('Pulling latest updates for all active managed repos:')
    update_specs_repo_and_known_hosts()
    repos_to_update = get_all_repos(active_only=True, include_specs_repo=False)
    with parallel_task_queue() as queue:
        log_to_client('Updating managed repos')
        for repo in repos_to_update:
            if not repo.is_overridden:
                repo.update_local_repo_async(queue, force=force)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def prep_for_start_local_env(pull_repos):
    if pull_repos:
        update_managed_repos(force=True)
    assembled_spec = spec_assembler.get_assembled_specs()
    if not assembled_spec[constants.CONFIG_BUNDLES_KEY]:
        raise RuntimeError('No bundles are activated. Use `dusty bundles` to activate bundles before running `dusty up`.')
    virtualbox.initialize_docker_vm()

Response:
Daemon - side command to ensure we re running the latest
    versions of any managed repos including the
    specs repo before we do anything else in the up flow.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def start_local_env(recreate_containers):

    assembled_spec = spec_assembler.get_assembled_specs()
    required_absent_assets = virtualbox.required_absent_assets(assembled_spec)
    if required_absent_assets:
        raise RuntimeError('Assets {} are specified as required but are not set. Set them with `dusty assets set`'.format(required_absent_assets))

    docker_ip = virtualbox.get_docker_vm_ip()

    # Stop will fail if we've never written a Composefile before
    if os.path.exists(constants.COMPOSEFILE_PATH):
        try:
            stop_apps_or_services(rm_containers=recreate_containers)
        except CalledProcessError as e:
            log_to_client("WARNING: docker-compose stop failed")
            log_to_client(str(e))

    daemon_warnings.clear_namespace('disk')
    df_info = virtualbox.get_docker_vm_disk_info(as_dict=True)
    if 'M' in df_info['free'] or 'K' in df_info['free']:
        warning_msg = 'VM is low on disk. Available disk: {}'.format(df_info['free'])
        daemon_warnings.warn('disk', warning_msg)
        log_to_client(warning_msg)

    log_to_client("Compiling together the assembled specs")
    active_repos = spec_assembler.get_all_repos(active_only=True, include_specs_repo=False)
    log_to_client("Compiling the port specs")
    port_spec = port_spec_compiler.get_port_spec_document(assembled_spec, docker_ip)
    log_to_client("Compiling the nginx config")
    docker_bridge_ip = virtualbox.get_docker_bridge_ip()
    nginx_config = nginx_compiler.get_nginx_configuration_spec(port_spec, docker_bridge_ip)
    log_to_client("Creating setup and script bash files")
    make_up_command_files(assembled_spec, port_spec)
    log_to_client("Compiling docker-compose config")
    compose_config = compose_compiler.get_compose_dict(assembled_spec, port_spec)

    log_to_client("Saving port forwarding to hosts file")
    hosts.update_hosts_file_from_port_spec(port_spec)
    log_to_client("Configuring NFS")
    nfs.configure_nfs()
    log_to_client("Saving updated nginx config to the VM")
    nginx.update_nginx_from_config(nginx_config)
    log_to_client("Saving Docker Compose config and starting all containers")
    compose.update_running_containers_from_spec(compose_config, recreate_containers=recreate_containers)

    log_to_client("Your local environment is now started!")

Response: This command will start the local environment and return the current environment.


Instruction:
Make a summary of the following Python 3 code
def stop_apps_or_services(app_or_service_names=None, rm_containers=False):
    if app_or_service_names:
        log_to_client("Stopping the following apps or services: {}".format(', '.join(app_or_service_names)))
    else:
        log_to_client("Stopping all running containers associated with Dusty")

    compose.stop_running_services(app_or_service_names)
    if rm_containers:
        compose.rm_containers(app_or_service_names)

Response: Stops any currently running Docker containers associated with the provided apps_or_services or removes the containers associated with the provided services_or_services. Does not remove the containers associated with the provided apps_or_services.


Instruction:
Write a Python 3 script for
restarting any containers associated with Dusty or associated with the provided app_or_service_names.

Response:
def restart_apps_or_services(app_or_service_names=None):
    """Restart any containers associated with Dusty, or associated with
    the provided app_or_service_names."""
    if app_or_service_names:
        log_to_client("Restarting the following apps or services: {}".format(', '.join(app_or_service_names)))
    else:
        log_to_client("Restarting all active containers associated with Dusty")

    if app_or_service_names:
        specs = spec_assembler.get_assembled_specs()
        specs_list = [specs['apps'][app_name] for app_name in app_or_service_names if app_name in specs['apps']]
        repos = set()
        for spec in specs_list:
            if spec['repo']:
                repos = repos.union(spec_assembler.get_same_container_repos_from_spec(spec))
        nfs.update_nfs_with_repos(repos)
    else:
        nfs.update_nfs_with_repos(spec_assembler.get_all_repos(active_only=True, include_specs_repo=False))
    compose.restart_running_services(app_or_service_names)


Instruction:
Create a Python 3 function for
returning a dictionary containing the Compose spec required to run Dusty s nginx container used for host forwarding.

Response:
def _compose_dict_for_nginx(port_specs):
    """Return a dictionary containing the Compose spec required to run
    Dusty's nginx container used for host forwarding."""
    spec = {'image': constants.NGINX_IMAGE,
            'volumes': ['{}:{}'.format(constants.NGINX_CONFIG_DIR_IN_VM, constants.NGINX_CONFIG_DIR_IN_CONTAINER)],
            'command': 'nginx -g "daemon off;" -c /etc/nginx/conf.d/nginx.primary',
            'container_name': 'dusty_{}_1'.format(constants.DUSTY_NGINX_NAME)}
    all_host_ports = set([nginx_spec['host_port'] for nginx_spec in port_specs['nginx']])
    if all_host_ports:
        spec['ports'] = []
        for port in all_host_ports:
            spec['ports'].append('{0}:{0}'.format(port))
    return {constants.DUSTY_NGINX_NAME: spec}


Instruction:
Can you generate the documentation for the following Python 3 function
def get_compose_dict(assembled_specs, port_specs):
    compose_dict = _compose_dict_for_nginx(port_specs)
    for app_name in assembled_specs['apps'].keys():
        compose_dict[app_name] = _composed_app_dict(app_name, assembled_specs, port_specs)
    for service_spec in assembled_specs['services'].values():
        compose_dict[service_spec.name] = _composed_service_dict(service_spec)
    return compose_dict

Response: This function returns a dictionary representation of a docker - compose. yml file based on assembled_specs and port_specs.


Instruction:
Make a summary of the following Python 3 code
def _conditional_links(assembled_specs, app_name):
    link_to_apps = []
    potential_links = assembled_specs['apps'][app_name]['conditional_links']
    for potential_link in potential_links['apps']:
        if potential_link in assembled_specs['apps']:
            link_to_apps.append(potential_link)
    for potential_link in potential_links['services']:
        if potential_link in assembled_specs['services']:
            link_to_apps.append(potential_link)
    return link_to_apps

Response: Given the assembled specs and app_name this function will return all apps and services specified in the assembled_specs and the app_name s conditional_links property.


Instruction:
Can you implement a function in Python 3 that
returns the path to the build file for the app.

Response:
def _get_build_path(app_spec):
    """ Given a spec for an app, returns the value of the `build` field for docker-compose.
    If the path is relative, it is expanded and added to the path of the app's repo. """
    if os.path.isabs(app_spec['build']):
        return app_spec['build']
    return os.path.join(Repo(app_spec['repo']).local_path, app_spec['build'])


Instruction:
Make a summary of the following Python 3 code
def _composed_app_dict(app_name, assembled_specs, port_specs):
    logging.info("Compose Compiler: Compiling dict for app {}".format(app_name))
    app_spec = assembled_specs['apps'][app_name]
    compose_dict = app_spec["compose"]
    _apply_env_overrides(env_overrides_for_app_or_service(app_name), compose_dict)
    if 'image' in app_spec and 'build' in app_spec:
        raise RuntimeError("image and build are both specified in the spec for {}".format(app_name))
    elif 'image' in app_spec:
        logging.info
        compose_dict['image'] = app_spec['image']
    elif 'build' in app_spec:
        compose_dict['build'] = _get_build_path(app_spec)
    else:
        raise RuntimeError("Neither image nor build was specified in the spec for {}".format(app_name))
    compose_dict['entrypoint'] = []
    compose_dict['command'] = _compile_docker_command(app_spec)
    compose_dict['container_name'] = "dusty_{}_1".format(app_name)
    logging.info("Compose Compiler: compiled command {}".format(compose_dict['command']))
    compose_dict['links'] = _links_for_app(app_spec, assembled_specs)
    logging.info("Compose Compiler: links {}".format(compose_dict['links']))
    compose_dict['volumes'] = compose_dict['volumes'] + _get_compose_volumes(app_name, assembled_specs)
    logging.info("Compose Compiler: volumes {}".format(compose_dict['volumes']))
    port_list = _get_ports_list(app_name, port_specs)
    if port_list:
        compose_dict['ports'] = port_list
    logging.info("Compose Compiler: ports {}".format(port_list))
    compose_dict['user'] = 'root'
    return compose_dict

Response: This function returns a dictionary of the docker - compose. yml specifications for one app.


Instruction:
Here you have a function in Python 3, explain what it does
def _composed_service_dict(service_spec):
    compose_dict = service_spec.plain_dict()
    _apply_env_overrides(env_overrides_for_app_or_service(service_spec.name), compose_dict)
    compose_dict.setdefault('volumes', []).append(_get_cp_volume_mount(service_spec.name))
    compose_dict['container_name'] = "dusty_{}_1".format(service_spec.name)
    return compose_dict

Response:
This function returns a dictionary of the docker_compose specifications
    for one service. Currently this is just the Dusty service spec with
    an additional volume mount to support Dusty s cp functionality.


Instruction:
How would you explain what the following Python 3 function does
def _get_ports_list(app_name, port_specs):
    if app_name not in port_specs['docker_compose']:
        return []
    return ["{}:{}".format(port_spec['mapped_host_port'], port_spec['in_container_port'])
            for port_spec in port_specs['docker_compose'][app_name]]

Response: Returns a list of formatted port mappings for an app


Instruction:
Here you have a function in Python 3, explain what it does
def validate_specs_from_path(specs_path):
    # Validation of fields with schemer is now down implicitly through get_specs_from_path
    # We are dealing with Dusty_Specs class in this file
    log_to_client("Validating specs at path {}".format(specs_path))
    if not os.path.exists(specs_path):
        raise RuntimeError("Specs path not found: {}".format(specs_path))
    specs = get_specs_from_path(specs_path)
    _check_bare_minimum(specs)
    _validate_spec_names(specs)
    _validate_cycle_free(specs)
    log_to_client("Validation Complete!")

Response: Validates Dusty specs at the given path.


Instruction:
Given the following Python 3 function, write the documentation
def _env_vars_from_file(filename):
    def split_env(env):
        if '=' in env:
            return env.split('=', 1)
        else:
            return env, None
    env = {}
    for line in open(filename, 'r'):
        line = line.strip()
        if line and not line.startswith('#'):
            k, v = split_env(line)
            env[k] = v
    return env

Response: This function takes a file and returns a dict of environment variables that can be used to set the environment variables of the current node.


Instruction:
Can you tell what is the following Python 3 function doing
def _get_dependent(dependent_type, name, specs, root_spec_type):
    spec = specs[root_spec_type].get(name)
    if spec is None:
        raise RuntimeError("{} {} was referenced but not found".format(root_spec_type, name))
    dependents = spec['depends'][dependent_type]
    all_dependents = set(dependents)
    for dep in dependents:
        all_dependents |= _get_dependent(dependent_type, dep, specs, dependent_type)
    return all_dependents

Response: Returns all of the dependents of the given name of type dependent_type


Instruction:
Here you have a function in Python 3, explain what it does
def _get_referenced_apps(specs):
    activated_bundles = specs[constants.CONFIG_BUNDLES_KEY].keys()
    all_active_apps = set()
    for active_bundle in activated_bundles:
        bundle_spec = specs[constants.CONFIG_BUNDLES_KEY].get(active_bundle)
        for app_name in bundle_spec['apps']:
            all_active_apps.add(app_name)
            all_active_apps |= _get_dependent('apps', app_name, specs, 'apps')
    return all_active_apps

Response: Returns a set of all apps that are required to run any bundle in the given specs.


Instruction:
Can you implement a function in Python 3 that
expands specs. apps. depends. libs to include any indirectly required libs

Response:
def _expand_libs_in_apps(specs):
    """
    Expands specs.apps.depends.libs to include any indirectly required libs
    """
    for app_name, app_spec in specs['apps'].iteritems():
        if 'depends' in app_spec and 'libs' in app_spec['depends']:
            app_spec['depends']['libs'] = _get_dependent('libs', app_name, specs, 'apps')


Instruction:
Can you tell what is the following Python 3 function doing
def _expand_libs_in_libs(specs):
    for lib_name, lib_spec in specs['libs'].iteritems():
        if 'depends' in lib_spec and 'libs' in lib_spec['depends']:
            lib_spec['depends']['libs'] = _get_dependent('libs', lib_name, specs, 'libs')

Response: Expands specs. libs. depends. libs to include any indirectly required libs


Instruction:
Can you write a function in Python 3 where it
returns all libs that are referenced in specs. apps. depends. libs

Response:
def _get_referenced_libs(specs):
    """
    Returns all libs that are referenced in specs.apps.depends.libs
    """
    active_libs = set()
    for app_spec in specs['apps'].values():
        for lib in app_spec['depends']['libs']:
            active_libs.add(lib)
    return active_libs


Instruction:
How would you explain what the following Python 3 function does
def _get_referenced_services(specs):
    active_services = set()
    for app_spec in specs['apps'].values():
        for service in app_spec['depends']['services']:
            active_services.add(service)
    for bundle_spec in specs['bundles'].values():
        for service in bundle_spec['services']:
            active_services.add(service)
    return active_services

Response: Returns all services that are referenced in the current project.


Instruction:
Explain what the following Python 3 code does
def get_repo_of_app_or_library(app_or_library_name):
    specs = get_specs()
    repo_name = specs.get_app_or_lib(app_or_library_name)['repo']
    if not repo_name:
        return None
    return Repo(repo_name)

Response: This function returns the corresponding Repo object for the given app or library name.


Instruction:
Given the following Python 3 function, write the documentation
def get_same_container_repos_from_spec(app_or_library_spec):
    repos = set()
    app_or_lib_repo = get_repo_of_app_or_library(app_or_library_spec.name)
    if app_or_lib_repo is not None:
        repos.add(app_or_lib_repo)
    for dependent_name in app_or_library_spec['depends']['libs']:
        repos.add(get_repo_of_app_or_library(dependent_name))
    return repos

Response: Given a spec of an app or library returns all repos that are guaranteed to live in the same container


Instruction:
Given the following Python 3 function, write the documentation
def get_same_container_repos(app_or_library_name):
    specs = get_expanded_libs_specs()
    spec = specs.get_app_or_lib(app_or_library_name)
    return get_same_container_repos_from_spec(spec)

Response: Given the name of an app or library returns all repos that are guaranteed to live in the same container


Instruction:
Can you tell what is the following Python 3 function doing
def _dusty_hosts_config(hosts_specs):
    rules =  ''.join(['{} {}\n'.format(spec['forwarded_ip'], spec['host_address']) for spec in hosts_specs])
    return config_file.create_config_section(rules)

Response: Return a string of all host rules required to match the given spec.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def update_hosts_file_from_port_spec(port_spec):
    logging.info('Updating hosts file to match port spec')
    hosts_specs = port_spec['hosts_file']
    current_hosts = config_file.read(constants.HOSTS_PATH)
    cleared_hosts = config_file.remove_current_dusty_config(current_hosts)
    updated_hosts = cleared_hosts + _dusty_hosts_config(hosts_specs)
    config_file.write(constants.HOSTS_PATH, updated_hosts)

Response:
Given a port spec update the hosts file specified at
    constants. HOSTS_PATH with the port mappings specified in the port spec.


Instruction:
How would you code a function in Python 3 to
move the temporary binary to the location of the original binary that s currently being run.

Response:
def _move_temp_binary_to_path(tmp_binary_path):
    """Moves the temporary binary to the location of the binary that's currently being run.
    Preserves owner, group, and permissions of original binary"""
    # pylint: disable=E1101
    binary_path = _get_binary_location()
    if not binary_path.endswith(constants.DUSTY_BINARY_NAME):
        raise RuntimeError('Refusing to overwrite binary {}'.format(binary_path))
    st = os.stat(binary_path)
    permissions = st.st_mode
    owner = st.st_uid
    group = st.st_gid
    shutil.move(tmp_binary_path, binary_path)
    os.chown(binary_path, owner, group)
    os.chmod(binary_path, permissions)
    return binary_path


Instruction:
Explain what the following Python 3 code does
def _nginx_stream_spec(port_spec, bridge_ip):
    server_string_spec = "\t server {\n"
    server_string_spec += "\t \t {}\n".format(_nginx_listen_string(port_spec))
    server_string_spec += "\t \t {}\n".format(_nginx_proxy_string(port_spec, bridge_ip))
    server_string_spec += "\t }\n"
    return server_string_spec

Response: This will output the nginx stream config string for specific port spec


Instruction:
Can you tell what is the following Python 3 function doing
def get_nginx_configuration_spec(port_spec_dict, docker_bridge_ip):
    nginx_http_config, nginx_stream_config = "", ""
    for port_spec in port_spec_dict['nginx']:
        if port_spec['type'] == 'http':
            nginx_http_config += _nginx_http_spec(port_spec, docker_bridge_ip)
        elif port_spec['type'] == 'stream':
            nginx_stream_config += _nginx_stream_spec(port_spec, docker_bridge_ip)
    return {'http': nginx_http_config, 'stream': nginx_stream_config}

Response: This function takes in a port spec dict and returns a nginx configuration string.


Instruction:
How would you explain what the following Python 3 function does
def memoized(fn):
    @functools.wraps(fn)
    def memoizer(*args, **kwargs):
        key = function_key(fn) + pickle.dumps(args) + pickle.dumps(_hash_kwargs(kwargs))
        if key not in cache:
            cache[key] = fn(*args, **kwargs)
        return cache[key]
    return memoizer

Response: Memoized version of the function.


Instruction:
Can you create a Python 3 function that
loads the SSH_AUTH_SOCK environment variable for the user.

Response:
def _load_ssh_auth_post_yosemite(mac_username):
    """Starting with Yosemite, launchd was rearchitected and now only one
    launchd process runs for all users. This allows us to much more easily
    impersonate a user through launchd and extract the environment
    variables from their running processes."""
    user_id = subprocess.check_output(['id', '-u', mac_username])
    ssh_auth_sock = subprocess.check_output(['launchctl', 'asuser', user_id, 'launchctl', 'getenv', 'SSH_AUTH_SOCK']).rstrip()
    _set_ssh_auth_sock(ssh_auth_sock)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _load_ssh_auth_pre_yosemite():
    for process in psutil.process_iter():
        if process.name() == 'ssh-agent':
            ssh_auth_sock = subprocess.check_output(['launchctl', 'bsexec', str(process.pid), 'launchctl', 'getenv', 'SSH_AUTH_SOCK']).rstrip()
            if ssh_auth_sock:
                _set_ssh_auth_sock(ssh_auth_sock)
                break
    else:
        daemon_warnings.warn('ssh', 'No running ssh-agent found linked to SSH_AUTH_SOCK')

Response: Load the SSH_AUTH_SOCK environment variable if running on a running ssh - agent.


Instruction:
Can you generate the documentation for the following Python 3 function
def check_and_load_ssh_auth():

    mac_username = get_config_value(constants.CONFIG_MAC_USERNAME_KEY)
    if not mac_username:
        logging.info("Can't setup ssh authorization; no mac_username specified")
        return
    if not _running_on_mac(): # give our Linux unit tests a way to not freak out
        logging.info("Skipping SSH load, we are not running on Mac")
        return

    if _mac_version_is_post_yosemite():
        _load_ssh_auth_post_yosemite(mac_username)
    else:
        _load_ssh_auth_pre_yosemite()

Response: Checks the user s config value and loads the SSH_AUTH_SOCK environment variable if it is present.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _cleanup_path(path):
    try:
        yield
    finally:
        if os.path.exists(path):
            if os.path.isdir(path):
                shutil.rmtree(path)
            else:
                os.remove(path)

Response:
Recursively delete a path upon exiting this context
    manager. Supports targets that are files or directories. Supports targets that are files or directories.


Instruction:
How would you explain what the following Python 3 function does
def copy_between_containers(source_name, source_path, dest_name, dest_path):
    if not container_path_exists(source_name, source_path):
        raise RuntimeError('ERROR: Path {} does not exist inside container {}.'.format(source_path, source_name))
    temp_path = os.path.join(tempfile.mkdtemp(), str(uuid.uuid1()))
    with _cleanup_path(temp_path):
        copy_to_local(temp_path, source_name, source_path, demote=False)
        copy_from_local(temp_path, dest_name, dest_path, demote=False)

Response: Copy a file from the source container to the destination container.


Instruction:
Here you have a function in Python 3, explain what it does
def copy_from_local(local_path, remote_name, remote_path, demote=True):
    if not os.path.exists(local_path):
        raise RuntimeError('ERROR: Path {} does not exist'.format(local_path))
    temp_identifier = str(uuid.uuid1())
    if os.path.isdir(local_path):
        sync_local_path_to_vm(local_path, os.path.join(vm_cp_path(remote_name), temp_identifier), demote=demote)
        move_dir_inside_container(remote_name, os.path.join(constants.CONTAINER_CP_DIR, temp_identifier), remote_path)
    else:
        sync_local_path_to_vm(local_path, os.path.join(vm_cp_path(remote_name), temp_identifier), demote=demote)
        move_file_inside_container(remote_name, os.path.join(constants.CONTAINER_CP_DIR, temp_identifier), remote_path)

Response:
Copy a path from the local filesystem to a path inside a Dusty
    container.


Instruction:
Write a Python 3 script for
copying a path from inside a Dusty container to a local filesystem.

Response:
def copy_to_local(local_path, remote_name, remote_path, demote=True):
    """Copy a path from inside a Dusty container to a path on the
    local filesystem. The path on the local filesystem must be
    wrist-accessible by the user specified in mac_username."""
    if not container_path_exists(remote_name, remote_path):
        raise RuntimeError('ERROR: Path {} does not exist inside container {}.'.format(remote_path, remote_name))
    temp_identifier = str(uuid.uuid1())
    copy_path_inside_container(remote_name, remote_path, os.path.join(constants.CONTAINER_CP_DIR, temp_identifier))
    vm_path = os.path.join(vm_cp_path(remote_name), temp_identifier)
    is_dir = vm_path_is_directory(vm_path)
    sync_local_path_from_vm(local_path, vm_path, demote=demote, is_dir=is_dir)


Instruction:
Can you implement a function in Python 3 that
mounts a nfs repository with the nfs server.

Response:
def _mount_repo(repo, wait_for_server=False):
    """
    This function will create the VM directory where a repo will be mounted, if it
    doesn't exist.  If wait_for_server is set, it will wait up to 10 seconds for
    the nfs server to start, by retrying mounts that fail with 'Connection Refused'.

    If wait_for_server is not set, it will attempt to run the mount command once
    """
    check_call_on_vm('sudo mkdir -p {}'.format(repo.vm_path))
    if wait_for_server:
        for i in range(0,10):
            try:
                _run_mount_command(repo)
                return
            except CalledProcessError as e:
                if 'Connection refused' in e.output:
                    logging.info('Failed to mount repo; waiting for nfsd to restart')
                    time.sleep(1)
                else:
                    logging.info(e.output)
                    raise e
        log_to_client('Failed to mount repo {}'.format(repo.short_name))
        raise RuntimeError('Unable to mount repo with NFS')
    else:
        _run_mount_command(repo)


Instruction:
Create a Python 3 function for
giving a dictionary containing the expanded dusty DAG specs this function will return a dictionary containing the port mappings needed by downstream methods. Currently this includes docker_compose, virtualbox, nginx and hosts_file.

Response:
def get_port_spec_document(expanded_active_specs, docker_vm_ip):
    """ Given a dictionary containing the expanded dusty DAG specs this function will
    return a dictionary containing the port mappings needed by downstream methods.  Currently
    this includes docker_compose, virtualbox, nginx and hosts_file."""
    forwarding_port = 65000
    port_spec = {'docker_compose':{}, 'nginx':[], 'hosts_file':[]}
    host_full_addresses, host_names, stream_host_ports = set(), set(), set()
    # No matter the order of apps in expanded_active_specs, we want to produce a consistent
    # port_spec with respect to the apps and the ports they are outputted on
    for app_name in sorted(expanded_active_specs['apps'].keys()):
        app_spec = expanded_active_specs['apps'][app_name]
        if 'host_forwarding' not in app_spec:
            continue
        port_spec['docker_compose'][app_name] = []
        for host_forwarding_spec in app_spec['host_forwarding']:
            # These functions are just used for validating the set of specs all works together
            _add_full_addresses(host_forwarding_spec, host_full_addresses)
            if host_forwarding_spec['type'] == 'stream':
                _add_stream_host_port(host_forwarding_spec, stream_host_ports)

            port_spec['docker_compose'][app_name].append(_docker_compose_port_spec(host_forwarding_spec, forwarding_port))
            port_spec['nginx'].append(_nginx_port_spec(host_forwarding_spec, forwarding_port, docker_vm_ip))

            _add_host_names(host_forwarding_spec, docker_vm_ip, port_spec, host_names)
            forwarding_port += 1
    return port_spec


Instruction:
Create a Python 3 function to
return the Docker registry host associated with a given image name.

Response:
def registry_from_image(image_name):
    """Returns the Docker registry host associated with
    a given image name."""
    if '/' not in image_name: # official image
        return constants.PUBLIC_DOCKER_REGISTRY
    prefix = image_name.split('/')[0]
    if '.' not in prefix: # user image on official repository, e.g. thieman/clojure
        return constants.PUBLIC_DOCKER_REGISTRY
    return prefix


Instruction:
Here you have a function in Python 3, explain what it does
def get_authed_registries():
    result = set()
    if not os.path.exists(constants.DOCKER_CONFIG_PATH):
        return result
    config = json.load(open(constants.DOCKER_CONFIG_PATH, 'r'))
    for registry in config.get('auths', {}).iterkeys():
        try:
            parsed = urlparse(registry)
        except Exception:
            log_to_client('Error parsing registry {} from Docker config, will skip this registry').format(registry)
        # This logic assumes the auth is either of the form
        # gamechanger.io (no scheme, no path after host) or
        # of the form https://index.docker.io/v1/ (scheme,
        # netloc parses correctly, additional path does not matter).
        # These are the formats I saw in my personal config file,
        # not sure what other formats it might accept.
        result.add(parsed.netloc) if parsed.netloc else result.add(parsed.path)
    return result

Response:
Reads the Docker client config file for the current user
    and returns all registries that are authorized by the user.


Instruction:
Write a Python 3 script for
putting the client logger into streaming mode.

Response:
def streaming_to_client():
    """Puts the client logger into streaming mode, which sends
    unbuffered input through to the socket one character at a time.
    We also disable propagation so the root logger does not
    receive many one-byte emissions. This context handler
    was originally created for streaming Compose up's
    terminal output through to the client and should only be
    used for similarly complex circumstances."""
    for handler in client_logger.handlers:
        if hasattr(handler, 'append_newlines'):
            break
    else:
        handler = None
    old_propagate = client_logger.propagate
    client_logger.propagate = False
    if handler is not None:
        old_append = handler.append_newlines
        handler.append_newlines = False
    yield
    client_logger.propagate = old_propagate
    if handler is not None:
        handler.append_newlines = old_append


Instruction:
Can you generate a brief explanation for the following Python 3 code
def pty_fork(*args):

    updated_env = copy(os.environ)
    updated_env.update(get_docker_env())
    args += (updated_env,)
    executable = args[0]
    demote_fn = demote_to_user(get_config_value(constants.CONFIG_MAC_USERNAME_KEY))

    child_pid, pty_fd = pty.fork()
    if child_pid == 0:
        demote_fn()
        os.execle(_executable_path(executable), *args)
    else:
        child_process = psutil.Process(child_pid)
        terminal = os.fdopen(pty_fd, 'r', 0)
        with streaming_to_client():
            while child_process.status() == 'running':
                output = terminal.read(1)
                log_to_client(output)
        _, exit_code = os.waitpid(child_pid, 0)
        if exit_code != 0:
            raise subprocess.CalledProcessError(exit_code, ' '.join(args[:-1]))

Response: Runs a subprocess with a PTY attached via fork and exec.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _compile_docker_commands(app_name, assembled_specs, port_spec):
    app_spec = assembled_specs['apps'][app_name]
    commands = ['set -e']
    commands += _lib_install_commands_for_app(app_name, assembled_specs)
    if app_spec['mount']:
        commands.append("cd {}".format(container_code_path(app_spec)))
        commands.append("export PATH=$PATH:{}".format(container_code_path(app_spec)))
    commands += _copy_assets_commands_for_app(app_spec, assembled_specs)
    commands += _get_once_commands(app_spec, port_spec)
    commands += _get_always_commands(app_spec)
    return commands

Response: Compile the docker commands for the given app.


Instruction:
Create a Python 3 function to
raise the open file handles permitted by the Dusty daemon process and its child processes.

Response:
def _increase_file_handle_limit():
    """Raise the open file handles permitted by the Dusty daemon process
    and its child processes. The number we choose here needs to be within
    the OS X default kernel hard limit, which is 10240."""
    logging.info('Increasing file handle limit to {}'.format(constants.FILE_HANDLE_LIMIT))
    resource.setrlimit(resource.RLIMIT_NOFILE,
                       (constants.FILE_HANDLE_LIMIT, resource.RLIM_INFINITY))


Instruction:
How would you implement a function in Python 3 that
starts the daemon s HTTP server on a separate thread.

Response:
def _start_http_server():
    """Start the daemon's HTTP server on a separate thread.
    This server is only used for servicing container status
    requests from Dusty's custom 502 page."""
    logging.info('Starting HTTP server at {}:{}'.format(constants.DAEMON_HTTP_BIND_IP,
                                                        constants.DAEMON_HTTP_BIND_PORT))
    thread = threading.Thread(target=http_server.app.run, args=(constants.DAEMON_HTTP_BIND_IP,
                                                                constants.DAEMON_HTTP_BIND_PORT))
    thread.daemon = True
    thread.start()


Instruction:
Explain what the following Python 3 code does
def get_dusty_images():
    specs = get_specs()
    dusty_image_names = [spec['image'] for spec in specs['apps'].values() + specs['services'].values() if 'image' in spec]
    dusty_images = set([name  if ':' in name else "{}:latest".format(name) for name in dusty_image_names])
    return dusty_images

Response: Returns all images listed in dusty specs in the form repository : tag.


Instruction:
Write a Python 3 script for
ripping off and slightly modified based on docker - py s kwargs_from_env utility function.

Response:
def get_docker_client():
    """Ripped off and slightly modified based on docker-py's
    kwargs_from_env utility function."""
    env = get_docker_env()
    host, cert_path, tls_verify = env['DOCKER_HOST'], env['DOCKER_CERT_PATH'], env['DOCKER_TLS_VERIFY']

    params = {'base_url': host.replace('tcp://', 'https://'),
              'timeout': None,
              'version': 'auto'}
    if tls_verify and cert_path:
        params['tls'] = docker.tls.TLSConfig(
            client_cert=(os.path.join(cert_path, 'cert.pem'),
                         os.path.join(cert_path, 'key.pem')),
            ca_cert=os.path.join(cert_path, 'ca.pem'),
            verify=True,
            ssl_version=None,
            assert_hostname=False)
    return docker.Client(**params)


Instruction:
Explain what the following Python 3 code does
def get_dusty_containers(services, include_exited=False):
    client = get_docker_client()
    if services:
        containers = [get_container_for_app_or_service(service, include_exited=include_exited) for service in services]
        return [container for container in containers if container]
    else:
        return [container
                for container in client.containers(all=include_exited)
                if any(name.startswith('/dusty') for name in container.get('Names', []))]

Response:
Get a list of containers associated with the list
    of services. If no services are provided attempts to generate a list of containers associated with Dusty.


Instruction:
Explain what the following Python 3 code does
def configure_nfs_server():
    repos_for_export = get_all_repos(active_only=True, include_specs_repo=False)

    current_exports = _get_current_exports()
    needed_exports = _get_exports_for_repos(repos_for_export)

    _ensure_managed_repos_dir_exists()

    if not needed_exports.difference(current_exports):
        if not _server_is_running():
            _restart_server()
        return

    _write_exports_config(needed_exports)
    _restart_server()

Response: This function will configure the nfs server with the current exports and the nusty exports needed for all currently active repos.


Instruction:
Can you write a function in Python 3 where it
ensures that the managed repositories directory exists.

Response:
def _ensure_managed_repos_dir_exists():
    """
    Our exports file will be invalid if this folder doesn't exist, and the NFS server
    will not run correctly.
    """
    if not os.path.exists(constants.REPOS_DIR):
        os.makedirs(constants.REPOS_DIR)


Instruction:
Given the following Python 3 function, write the documentation
def register_consumer():
    global _consumers
    hostname, port = request.form['hostname'], request.form['port']

    app_name = _app_name_from_forwarding_info(hostname, port)
    containers = get_dusty_containers([app_name], include_exited=True)
    if not containers:
        raise ValueError('No container exists for app {}'.format(app_name))
    container = containers[0]

    new_id = uuid1()
    new_consumer = Consumer(container['Id'], datetime.utcnow())
    _consumers[str(new_id)] = new_consumer

    response = jsonify({'app_name': app_name, 'consumer_id': new_id})
    response.headers['Access-Control-Allow-Origin'] = '*'
    response.headers['Access-Control-Allow-Methods'] = 'GET, POST'
    return response

Response: Register a consumer for accessing logs from a node.


Instruction:
Make a summary of the following Python 3 code
def consume(consumer_id):
    global _consumers
    consumer = _consumers[consumer_id]

    client = get_docker_client()
    try:
        status = client.inspect_container(consumer.container_id)['State']['Status']
    except Exception as e:
        status = 'unknown'
    new_logs = client.logs(consumer.container_id,
                           stdout=True,
                           stderr=True,
                           stream=False,
                           timestamps=False,
                           since=calendar.timegm(consumer.offset.timetuple()))

    updated_consumer = Consumer(consumer.container_id, datetime.utcnow())
    _consumers[str(consumer_id)] = updated_consumer

    response = jsonify({'logs': new_logs, 'status': status})
    response.headers['Access-Control-Allow-Origin'] = '*'
    response.headers['Access-Control-Allow-Methods'] = 'GET, POST'
    return response

Response:
Given an existing consumer ID return any new lines from the
    log since the last time the consumer was consumed.


Instruction:
Write a Python 3 script to
return a list of the formatted volume specs for a lib

Response:
def get_lib_volume_mounts(base_lib_name, assembled_specs):
    """ Returns a list of the formatted volume specs for a lib"""
    volumes = [_get_lib_repo_volume_mount(assembled_specs['libs'][base_lib_name])]
    volumes.append(get_command_files_volume_mount(base_lib_name, test=True))
    for lib_name in assembled_specs['libs'][base_lib_name]['depends']['libs']:
        lib_spec = assembled_specs['libs'][lib_name]
        volumes.append(_get_lib_repo_volume_mount(lib_spec))
    return volumes


Instruction:
Can you tell what is the following Python 3 function doing
def _get_app_libs_volume_mounts(app_name, assembled_specs):
    volumes = []
    for lib_name in assembled_specs['apps'][app_name]['depends']['libs']:
        lib_spec = assembled_specs['libs'][lib_name]
        volumes.append("{}:{}".format(Repo(lib_spec['repo']).vm_path, container_code_path(lib_spec)))
    return volumes

Response: Returns a list of the formatted volume mounts for all libs that an app uses.


Instruction:
Explain what the following Python 3 code does
def _dusty_vm_exists():
    existing_vms = check_output_demoted(['VBoxManage', 'list', 'vms'])
    for line in existing_vms.splitlines():
        if '"{}"'.format(constants.VM_MACHINE_NAME) in line:
            return True
    return False

Response: Check if a VM exists in the VBox or Docker Machine.


Instruction:
Write a Python 3 script to
initialize the Dusty VM if it does not already exist.

Response:
def _init_docker_vm():
    """Initialize the Dusty VM if it does not already exist."""
    if not _dusty_vm_exists():
        log_to_client('Initializing new Dusty VM with Docker Machine')
        machine_options = ['--driver', 'virtualbox',
                           '--virtualbox-cpu-count', '-1',
                           '--virtualbox-boot2docker-url', constants.CONFIG_BOOT2DOCKER_URL,
                           '--virtualbox-memory', str(get_config_value(constants.CONFIG_VM_MEM_SIZE)),
                           '--virtualbox-hostonly-nictype', constants.VM_NIC_TYPE]
        check_call_demoted(['docker-machine', 'create'] + machine_options + [constants.VM_MACHINE_NAME],
                           redirect_stderr=True)


Instruction:
Write a Python 3 function that can
start the Dusty VM if it is not already running.

Response:
def _start_docker_vm():
    """Start the Dusty VM if it is not already running."""
    is_running = docker_vm_is_running()
    if not is_running:
        log_to_client('Starting docker-machine VM {}'.format(constants.VM_MACHINE_NAME))
        _apply_nat_dns_host_resolver()
        _apply_nat_net_less_greedy_subnet()
        check_and_log_output_and_error_demoted(['docker-machine', 'start', constants.VM_MACHINE_NAME], quiet_on_success=True)
    return is_running


Instruction:
How would you explain what the following Python 3 function does
def docker_vm_is_running():
    running_vms = check_output_demoted(['VBoxManage', 'list', 'runningvms'])
    for line in running_vms.splitlines():
        if '"{}"'.format(constants.VM_MACHINE_NAME) in line:
            return True
    return False

Response: Using VBoxManage is 0. 5 seconds or so faster than Machine.


Instruction:
Write a Python 3 script for
returning the MAC address assigned to the host - only adapter using output from VBoxManage.

Response:
def _get_host_only_mac_address():
    """Returns the MAC address assigned to the host-only adapter,
    using output from VBoxManage. Returned MAC address has no colons
    and is lower-cased."""
    # Get the number of the host-only adapter
    vm_config = _get_vm_config()
    for line in vm_config:
        if line.startswith('hostonlyadapter'):
            adapter_number = int(line[15:16])
            break
    else:
        raise ValueError('No host-only adapter is defined for the Dusty VM')

    for line in vm_config:
        if line.startswith('macaddress{}'.format(adapter_number)):
            return line.split('=')[1].strip('"').lower()
    raise ValueError('Could not find MAC address for adapter number {}'.format(adapter_number))


Instruction:
Explain what the following Python 3 code does
def _ip_for_mac_from_ip_addr_show(ip_addr_show, target_mac):
    return_next_ip = False
    for line in ip_addr_show.splitlines():
        line = line.strip()
        if line.startswith('link/ether'):
            line_mac = line.split(' ')[1].replace(':', '')
            if line_mac == target_mac:
                return_next_ip = True
        elif return_next_ip and line.startswith('inet') and not line.startswith('inet6'):
            ip = line.split(' ')[1].split('/')[0]
            return ip

Response: Given a rather - complex output from a ip addr show command returns the IP address that is assigned to the interface with the given MAC.


Instruction:
Given the following Python 3 function, write the documentation
def _get_host_only_ip():
    mac = _get_host_only_mac_address()
    ip_addr_show = check_output_demoted(['ssh', '-o', 'StrictHostKeyChecking=no',
                                         '-o', 'UserKnownHostsFile=/dev/null',
                                         '-i', _vm_key_path(), '-p', _get_localhost_ssh_port(),
                                         'docker@127.0.0.1', 'ip addr show'])
    return _ip_for_mac_from_ip_addr_show(ip_addr_show, mac)

Response:
Determine the host - only IP of the Dusty VM through Virtualbox and SSH
    directly bypassing Docker Machine.


Instruction:
How would you explain what the following Python 3 function does
def create_local_copy(cookie_file):
    # if type of cookie_file is a list, use the first element in the list
    if isinstance(cookie_file, list):
        cookie_file = cookie_file[0]

    # check if cookie file exists
    if os.path.exists(cookie_file):
        # copy to random name in tmp folder
        tmp_cookie_file = tempfile.NamedTemporaryFile(suffix='.sqlite').name
        open(tmp_cookie_file, 'wb').write(open(cookie_file, 'rb').read())
        return tmp_cookie_file
    else:
        raise BrowserCookieError('Can not find cookie file at: ' + cookie_file)

Response: Create a local copy of the sqlite cookie database and return the new filename.


Instruction:
Here you have a function in Python 3, explain what it does
def create_cookie(host, path, secure, expires, name, value):
    return http.cookiejar.Cookie(0, name, value, None, False, host, host.startswith('.'), host.startswith('.'), path,
                                 True, secure, expires, False, None, None, {})

Response: Shortcut function to create a cookie


Instruction:
Explain what the following Python 3 code does
def load(domain_name=""):
    cj = http.cookiejar.CookieJar()
    for cookie_fn in [chrome, firefox]:
        try:
            for cookie in cookie_fn(domain_name=domain_name):
                cj.set_cookie(cookie)
        except BrowserCookieError:
            pass
    return cj

Response: Try to load cookies from all supported browsers and return a combined cookiejar.


Instruction:
How would you explain what the following Python 3 function does
def load(self):
        con = sqlite3.connect(self.tmp_cookie_file)
        cur = con.cursor()
        try:
            # chrome <=55
            cur.execute('SELECT host_key, path, secure, expires_utc, name, value, encrypted_value '
                        'FROM cookies WHERE host_key like "%{}%";'.format(self.domain_name))
        except sqlite3.OperationalError:
            # chrome >=56
            cur.execute('SELECT host_key, path, is_secure, expires_utc, name, value, encrypted_value '
                        'FROM cookies WHERE host_key like "%{}%";'.format(self.domain_name))

        cj = http.cookiejar.CookieJar()
        for item in cur.fetchall():
            host, path, secure, expires, name = item[:5]
            value = self._decrypt(item[5], item[6])
            c = create_cookie(host, path, secure, expires, name, value)
            cj.set_cookie(c)
        con.close()
        return cj

Response: Load sqlite cookies into a cookiejar


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _randone(d, limit=20, grouprefs=None):
    if grouprefs is None:
        grouprefs = {}
    """docstring for _randone"""
    ret = ''
    for i in d:
        if i[0] == sre_parse.IN:
            ret += choice(_in(i[1]))
        elif i[0] == sre_parse.LITERAL:
            ret += unichr(i[1])
        elif i[0] == sre_parse.CATEGORY:
            ret += choice(CATEGORIES.get(i[1], ['']))
        elif i[0] == sre_parse.ANY:
            ret += choice(CATEGORIES['category_any'])
        elif i[0] == sre_parse.MAX_REPEAT or i[0] == sre_parse.MIN_REPEAT:
            if i[1][1] + 1 - i[1][0] >= limit:
                min, max = i[1][0], i[1][0] + limit - 1
            else:
                min, max = i[1][0], i[1][1]
            for _ in range(randint(min, max)):
                ret += _randone(list(i[1][2]), limit, grouprefs)
        elif i[0] == sre_parse.BRANCH:
            ret += _randone(choice(i[1][1]), limit, grouprefs)
        elif i[0] == sre_parse.SUBPATTERN or i[0] == sre_parse.ASSERT:
            subexpr = i[1][1]
            if IS_PY36_OR_GREATER and i[0] == sre_parse.SUBPATTERN:
                subexpr = i[1][3]
            subp = _randone(subexpr, limit, grouprefs)
            if i[1][0]:
                grouprefs[i[1][0]] = subp
            ret += subp
        elif i[0] == sre_parse.AT:
            continue
        elif i[0] == sre_parse.NOT_LITERAL:
            c = list(CATEGORIES['category_any'])
            if unichr(i[1]) in c:
                c.remove(unichr(i[1]))
            ret += choice(c)
        elif i[0] == sre_parse.GROUPREF:
            ret += grouprefs[i[1]]
        elif i[0] == sre_parse.ASSERT_NOT:
            pass
        else:
            print('[!] cannot handle expression "%s"' % str(i))

    return ret

Response: Return a random string from the list d.


Instruction:
Here you have a function in Python 3, explain what it does
def sre_to_string(sre_obj, paren=True):
    ret = u''
    for i in sre_obj:
        if i[0] == sre_parse.IN:
            prefix = ''
            if len(i[1]) and i[1][0][0] == sre_parse.NEGATE:
                prefix = '^'
            ret += u'[{0}{1}]'.format(prefix, sre_to_string(i[1], paren=paren))
        elif i[0] == sre_parse.LITERAL:
            u = unichr(i[1])
            ret += u if u not in sre_parse.SPECIAL_CHARS else '\\{0}'.format(u)
        elif i[0] == sre_parse.CATEGORY:
            ret += REVERSE_CATEGORIES[i[1]]
        elif i[0] == sre_parse.ANY:
            ret += '.'
        elif i[0] == sre_parse.BRANCH:
            # TODO simplifications here
            parts = [sre_to_string(x, paren=paren) for x in i[1][1]]
            if not any(parts):
                continue
            if i[1][0]:
                if len(parts) == 1:
                    paren = False
                prefix = ''
            else:
                prefix = '?:'
            branch = '|'.join(parts)
            if paren:
                ret += '({0}{1})'.format(prefix, branch)
            else:
                ret += '{0}'.format(branch)
        elif i[0] == sre_parse.SUBPATTERN:
            subexpr = i[1][1]
            if IS_PY36_OR_GREATER and i[0] == sre_parse.SUBPATTERN:
                subexpr = i[1][3]
            if i[1][0]:
                ret += '({0})'.format(sre_to_string(subexpr, paren=False))
            else:
                ret += '{0}'.format(sre_to_string(subexpr, paren=paren))
        elif i[0] == sre_parse.NOT_LITERAL:
            ret += '[^{0}]'.format(unichr(i[1]))
        elif i[0] == sre_parse.MAX_REPEAT:
            if i[1][0] == i[1][1]:
                range_str = '{{{0}}}'.format(i[1][0])
            else:
                if i[1][0] == 0 and i[1][1] - i[1][0] == sre_parse.MAXREPEAT:
                    range_str = '*'
                elif i[1][0] == 1 and i[1][1] - i[1][0] == sre_parse.MAXREPEAT - 1:
                    range_str = '+'
                else:
                    range_str = '{{{0},{1}}}'.format(i[1][0], i[1][1])
            ret += sre_to_string(i[1][2], paren=paren) + range_str
        elif i[0] == sre_parse.MIN_REPEAT:
            if i[1][0] == 0 and i[1][1] == sre_parse.MAXREPEAT:
                range_str = '*?'
            elif i[1][0] == 1 and i[1][1] == sre_parse.MAXREPEAT:
                range_str = '+?'
            elif i[1][1] == sre_parse.MAXREPEAT:
                range_str = '{{{0},}}?'.format(i[1][0])
            else:
                range_str = '{{{0},{1}}}?'.format(i[1][0], i[1][1])
            ret += sre_to_string(i[1][2], paren=paren) + range_str
        elif i[0] == sre_parse.GROUPREF:
            ret += '\\{0}'.format(i[1])
        elif i[0] == sre_parse.AT:
            if i[1] == sre_parse.AT_BEGINNING:
                ret += '^'
            elif i[1] == sre_parse.AT_END:
                ret += '$'
        elif i[0] == sre_parse.NEGATE:
            pass
        elif i[0] == sre_parse.RANGE:
            ret += '{0}-{1}'.format(unichr(i[1][0]), unichr(i[1][1]))
        elif i[0] == sre_parse.ASSERT:
            if i[1][0]:
                ret += '(?={0})'.format(sre_to_string(i[1][1], paren=False))
            else:
                ret += '{0}'.format(sre_to_string(i[1][1], paren=paren))
        elif i[0] == sre_parse.ASSERT_NOT:
            pass
        else:
            print('[!] cannot handle expression "%s"' % str(i))
    return ret

Response: Convert a sre_parse object to a string of the n - tuple structure.


Instruction:
Here you have a function in Python 3, explain what it does
def ib64_patched(self, attrsD, contentparams):
    if attrsD.get("mode", "") == "base64":
        return 0
    if self.contentparams["type"].startswith("text/"):
        return 0
    if self.contentparams["type"].endswith("+xml"):
        return 0
    if self.contentparams["type"].endswith("/xml"):
        return 0
    if self.contentparams["type"].endswith("/json"):
        return 0
    return 0

Response: Patch isBase64 to prevent Base64 encoding of JSON content


Instruction:
Can you generate a brief explanation for the following Python 3 code
def cleanwrap(func):

    def enc(self, *args, **kwargs):
        """ Send each item to _cleanup() """
        return (func(self, item, **kwargs) for item in args)

    return enc

Response: Wrapper for Zotero. _cleanup


Instruction:
Make a summary of the following Python 3 code
def ss_wrap(func):

    def wrapper(self, *args, **kwargs):
        if not self.savedsearch:
            self.savedsearch = SavedSearch(self)
        return func(self, *args, **kwargs)

    return wrapper

Response: Decorator that ensures that a SavedSearch object exists


Instruction:
Given the following Python 3 function, write the documentation
def error_handler(req):
    error_codes = {
        400: ze.UnsupportedParams,
        401: ze.UserNotAuthorised,
        403: ze.UserNotAuthorised,
        404: ze.ResourceNotFound,
        409: ze.Conflict,
        412: ze.PreConditionFailed,
        413: ze.RequestEntityTooLarge,
        428: ze.PreConditionRequired,
        429: ze.TooManyRequests,
    }

    def err_msg(req):
        """ Return a nicely-formatted error message
        """
        return "\nCode: %s\nURL: %s\nMethod: %s\nResponse: %s" % (
            req.status_code,
            # error.msg,
            req.url,
            req.request.method,
            req.text,
        )

    if error_codes.get(req.status_code):
        # check to see whether its 429
        if req.status_code == 429:
            # call our back-off function
            delay = backoff.delay
            if delay > 32:
                # we've waited a total of 62 seconds (2 + 4 … + 32), so give up
                backoff.reset()
                raise ze.TooManyRetries(
                    "Continuing to receive HTTP 429 \
responses after 62 seconds. You are being rate-limited, try again later"
                )
            time.sleep(delay)
            sess = requests.Session()
            new_req = sess.send(req.request)
            try:
                new_req.raise_for_status()
            except requests.exceptions.HTTPError:
                error_handler(new_req)
        else:
            raise error_codes.get(req.status_code)(err_msg(req))
    else:
        raise ze.HTTPError(err_msg(req))

Response: Error handler for HTTP requests


Instruction:
Here you have a function in Python 3, explain what it does
def default_headers(self):
        _headers = {
            "User-Agent": "Pyzotero/%s" % __version__,
            "Zotero-API-Version": "%s" % __api_version__,
        }
        if self.api_key:
            _headers["Authorization"] = "Bearer %s" % self.api_key
        return _headers

Response: Returns a dictionary of default headers for the current Zotero instance.


Instruction:
Can you implement a function in Python 3 that
adds a template to the cache for 304 checking accepts a dict and key name adds the retrieval time to self. templates as a new dict using the specified key

Response:
def _cache(self, response, key):
        """
        Add a retrieved template to the cache for 304 checking
        accepts a dict and key name, adds the retrieval time, and adds both
        to self.templates as a new dict using the specified key
        """
        # cache template and retrieval time for subsequent calls
        thetime = datetime.datetime.utcnow().replace(tzinfo=pytz.timezone("GMT"))
        self.templates[key] = {"tmplt": response.json(), "updated": thetime}
        return copy.deepcopy(response.json())


Instruction:
Can you implement a function in Python 3 that
removes keys we added for internal use

Response:
def _cleanup(self, to_clean, allow=()):
        """ Remove keys we added for internal use
        """
        # this item's been retrieved from the API, we only need the 'data'
        # entry
        if to_clean.keys() == ["links", "library", "version", "meta", "key", "data"]:
            to_clean = to_clean["data"]
        return dict(
            [
                [k, v]
                for k, v in list(to_clean.items())
                if (k in allow or k not in self.temp_keys)
            ]
        )


Instruction:
Given the following Python 3 function, write the documentation
def _retrieve_data(self, request=None):
        full_url = "%s%s" % (self.endpoint, request)
        # The API doesn't return this any more, so we have to cheat
        self.self_link = request
        self.request = requests.get(url=full_url, headers=self.default_headers())
        self.request.encoding = "utf-8"
        try:
            self.request.raise_for_status()
        except requests.exceptions.HTTPError:
            error_handler(self.request)
        return self.request

Response: Retrieve Zotero items via the API and return a JSON document containing the Zotero items.


Instruction:
How would you implement a function in Python 3 that
extracts self first next last links from a request response

Response:
def _extract_links(self):
        """
        Extract self, first, next, last links from a request response
        """
        extracted = dict()
        try:
            for key, value in self.request.links.items():
                parsed = urlparse(value["url"])
                fragment = "{path}?{query}".format(path=parsed[2], query=parsed[4])
                extracted[key] = fragment
            # add a 'self' link
            parsed = list(urlparse(self.self_link))
            # strip 'format' query parameter
            stripped = "&".join(
                [
                    "%s=%s" % (p[0], p[1])
                    for p in parse_qsl(parsed[4])
                    if p[0] != "format"
                ]
            )
            # rebuild url fragment
            # this is a death march
            extracted["self"] = urlunparse(
                [parsed[0], parsed[1], parsed[2], parsed[3], stripped, parsed[5]]
            )
            return extracted
        except KeyError:
            # No links present, because it's a single item
            return None


Instruction:
Write a Python 3 function for
checking if a resource is updated in the library

Response:
def _updated(self, url, payload, template=None):
        """
        Generic call to see if a template request returns 304
        accepts:
        - a string to combine with the API endpoint
        - a dict of format values, in case they're required by 'url'
        - a template name to check for
        As per the API docs, a template less than 1 hour old is
        assumed to be fresh, and will immediately return False if found
        """
        # If the template is more than an hour old, try a 304
        if (
            abs(
                datetime.datetime.utcnow().replace(tzinfo=pytz.timezone("GMT"))
                - self.templates[template]["updated"]
            ).seconds
            > 3600
        ):
            query = self.endpoint + url.format(
                u=self.library_id, t=self.library_type, **payload
            )
            headers = {
                "If-Modified-Since": payload["updated"].strftime(
                    "%a, %d %b %Y %H:%M:%S %Z"
                )
            }
            headers.update(self.default_headers())
            # perform the request, and check whether the response returns 304
            req = requests.get(query, headers=headers)
            try:
                req.raise_for_status()
            except requests.exceptions.HTTPError:
                error_handler(req)
            return req.status_code == 304
        # Still plenty of life left in't
        return False


Instruction:
How would you code a function in Python 3 to
add URL parameters to the current object

Response:
def add_parameters(self, **params):
        """
        Add URL parameters
        Also ensure that only valid format/content combinations are requested
        """
        self.url_params = None
        # we want JSON by default
        if not params.get("format"):
            params["format"] = "json"
        # non-standard content must be retrieved as Atom
        if params.get("content"):
            params["format"] = "atom"
        # TODO: rewrite format=atom, content=json request
        if "limit" not in params or params.get("limit") == 0:
            params["limit"] = 100
        # Need ability to request arbitrary number of results for version
        # response
        # -1 value is hack that works with current version
        elif params["limit"] == -1 or params["limit"] is None:
            del params["limit"]
        # bib format can't have a limit
        if params.get("format") == "bib":
            del params["limit"]
        self.url_params = urlencode(params, doseq=True)


Instruction:
Write a Python 3 function that can
build the URL query string for the user key.

Response:
def _build_query(self, query_string, no_params=False):
        """
        Set request parameters. Will always add the user ID if it hasn't
        been specifically set by an API method
        """
        try:
            query = quote(query_string.format(u=self.library_id, t=self.library_type))
        except KeyError as err:
            raise ze.ParamNotPassed("There's a request parameter missing: %s" % err)
        # Add the URL parameters and the user key, if necessary
        if no_params is False:
            if not self.url_params:
                self.add_parameters()
            query = "%s?%s" % (query, self.url_params)
        return query


Instruction:
Can you create a Python 3 function that
returns the contents of My Publications

Response:
def publications(self):
        """ Return the contents of My Publications
        """
        if self.library_type != "users":
            raise ze.CallDoesNotExist(
                "This API call does not exist for group libraries"
            )
        query_string = "/{t}/{u}/publications/items"
        return self._build_query(query_string)


Instruction:
Explain what the following Python 3 code does
def num_collectionitems(self, collection):
        query = "/{t}/{u}/collections/{c}/items".format(
            u=self.library_id, t=self.library_type, c=collection.upper()
        )
        return self._totals(query)

Response: Return the total number of items in the specified collection


Instruction:
Can you tell what is the following Python 3 function doing
def num_tagitems(self, tag):
        query = "/{t}/{u}/tags/{ta}/items".format(
            u=self.library_id, t=self.library_type, ta=tag
        )
        return self._totals(query)

Response: Return the total number of items for the specified tag


Instruction:
How would you explain what the following Python 3 function does
def key_info(self, **kwargs):
        query_string = "/keys/{k}".format(k=self.api_key)
        return self._build_query(query_string)

Response: Retrieve info about the permissions associated with the given Zotero instance.


Instruction:
Make a summary of the following Python 3 code
def fulltext_item(self, itemkey, **kwargs):
        query_string = "/{t}/{u}/items/{itemkey}/fulltext".format(
            t=self.library_type, u=self.library_id, itemkey=itemkey
        )
        return self._build_query(query_string)

Response: Get full - text content for an item


Instruction:
How would you explain what the following Python 3 function does
def set_fulltext(self, itemkey, payload):
        headers = self.default_headers()
        headers.update({"Content-Type": "application/json"})
        req = requests.put(
            url=self.endpoint
            + "/{t}/{u}/items/{k}/fulltext".format(
                t=self.library_type, u=self.library_id, k=itemkey
            ),
            headers=headers,
            data=json.dumps(payload),
        )
        try:
            req.raise_for_status()
        except requests.exceptions.HTTPError:
            error_handler(req)
        return True

Response: Set full - text data for an itemkey.


Instruction:
Can you tell what is the following Python 3 function doing
def new_fulltext(self, version):
        query_string = "/{t}/{u}/fulltext".format(
            t=self.library_type, u=self.library_id
        )
        headers = {"since": str(version)}
        headers.update(self.default_headers())
        req = requests.get(self.endpoint + query_string, headers=headers)
        try:
            req.raise_for_status()
        except requests.exceptions.HTTPError:
            error_handler(req)
        return req.json()

Response:
Retrieve list of full - text content items and versions which are newer
            than version.


Instruction:
Can you write a function in Python 3 where it
gets the last modified version of the resource.

Response:
def last_modified_version(self, **kwargs):
        """ Get the last modified version
        """
        self.items(**kwargs)
        return int(self.request.headers.get("last-modified-version", 0))


Instruction:
Make a summary of the following Python 3 code
def file(self, item, **kwargs):
        query_string = "/{t}/{u}/items/{i}/file".format(
            u=self.library_id, t=self.library_type, i=item.upper()
        )
        return self._build_query(query_string, no_params=True)

Response: Get the file from an specific item


Instruction:
Make a summary of the following Python 3 code
def dump(self, itemkey, filename=None, path=None):
        if not filename:
            filename = self.item(itemkey)["data"]["filename"]
        if path:
            pth = os.path.join(path, filename)
        else:
            pth = filename
        file = self.file(itemkey)
        if self.snapshot:
            self.snapshot = False
            pth = pth + ".zip"
        with open(pth, "wb") as f:
            f.write(file)

Response: Dump a file attachment to disk with optional filename and path.


Instruction:
Create a Python 3 function for
getting all the subcollections of a specific collection

Response:
def collections_sub(self, collection, **kwargs):
        """ Get subcollections for a specific collection
        """
        query_string = "/{t}/{u}/collections/{c}/collections".format(
            u=self.library_id, t=self.library_type, c=collection.upper()
        )
        return self._build_query(query_string)


Instruction:
Write a Python 3 function for
getting tags for the current user

Response:
def tags(self, **kwargs):
        """ Get tags
        """
        query_string = "/{t}/{u}/tags"
        self.tag_data = True
        return self._build_query(query_string)


Instruction:
Implement a Python 3 function for
iterating over the next set of links.

Response:
def iterfollow(self):
        """ Generator for self.follow()
        """
        # use same criterion as self.follow()
        if self.links is None:
            return
        if self.links.get("next"):
            yield self.follow()
        else:
            raise StopIteration


Instruction:
Can you generate the documentation for the following Python 3 function
def everything(self, query):
        try:
            items = []
            items.extend(query)
            while self.links.get("next"):
                items.extend(self.follow())
        except TypeError:
            # we have a bibliography object ughh
            items = copy.deepcopy(query)
            while self.links.get("next"):
                items.entries.extend(self.follow().entries)
        return items

Response: Retrieve all items in the library for a particular query


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_subset(self, subset):
        if len(subset) > 50:
            raise ze.TooManyItems("You may only retrieve 50 items per call")
        # remember any url parameters that have been set
        params = self.url_params
        retr = []
        for itm in subset:
            retr.extend(self.item(itm))
            self.url_params = params
        # clean up URL params when we're finished
        self.url_params = None
        return retr

Response: Retrieve a subset of items from the cache


Instruction:
Can you create a Python 3 function that
processes the JSON data returned by the API call.

Response:
def _json_processor(self, retrieved):
        """ Format and return data from API calls which return Items
        """
        json_kwargs = {}
        if self.preserve_json_order:
            json_kwargs["object_pairs_hook"] = OrderedDict
        # send entries to _tags_data if there's no JSON
        try:
            items = [
                json.loads(e["content"][0]["value"], **json_kwargs)
                for e in retrieved.entries
            ]
        except KeyError:
            return self._tags_data(retrieved)
        return items


Instruction:
Create a Python 3 function for
returning a list of dicts which are dumped CSL JSON

Response:
def _csljson_processor(self, retrieved):
        """ Return a list of dicts which are dumped CSL JSON
        """
        items = []
        json_kwargs = {}
        if self.preserve_json_order:
            json_kwargs["object_pairs_hook"] = OrderedDict
        for csl in retrieved.entries:
            items.append(json.loads(csl["content"][0]["value"], **json_kwargs))
        self.url_params = None
        return items


Instruction:
Write a Python 3 script for
returning a list of strings formatted as HTML bibliography entries

Response:
def _bib_processor(self, retrieved):
        """ Return a list of strings formatted as HTML bibliography entries
        """
        items = []
        for bib in retrieved.entries:
            items.append(bib["content"][0]["value"])
        self.url_params = None
        return items


Instruction:
How would you code a function in Python 3 to
return a list of strings formatted as HTML citation entries

Response:
def _citation_processor(self, retrieved):
        """ Return a list of strings formatted as HTML citation entries
        """
        items = []
        for cit in retrieved.entries:
            items.append(cit["content"][0]["value"])
        self.url_params = None
        return items


Instruction:
Explain what the following Python 3 code does
def item_template(self, itemtype):
        # if we have a template and it hasn't been updated since we stored it
        template_name = "item_template_" + itemtype
        query_string = "/items/new?itemType={i}".format(i=itemtype)
        if self.templates.get(template_name) and not self._updated(
            query_string, self.templates[template_name], template_name
        ):
            return copy.deepcopy(self.templates[template_name]["tmplt"])
        # otherwise perform a normal request and cache the response
        retrieved = self._retrieve_data(query_string)
        return self._cache(retrieved, template_name)

Response: Get a template for a new item type


Instruction:
Here you have a function in Python 3, explain what it does
def _attachment(self, payload, parentid=None):
        attachment = Zupload(self, payload, parentid)
        res = attachment.upload()
        return res

Response: Create attachments with the given payload and parentid.


Instruction:
Can you tell what is the following Python 3 function doing
def show_condition_operators(self, condition):
        # dict keys of allowed operators for the current condition
        permitted_operators = self.savedsearch.conditions_operators.get(condition)
        # transform these into values
        permitted_operators_list = set(
            [self.savedsearch.operators.get(op) for op in permitted_operators]
        )
        return permitted_operators_list

Response: Show available operators for a given saved search condition


Instruction:
Make a summary of the following Python 3 code
def saved_search(self, name, conditions):
        self.savedsearch._validate(conditions)
        payload = [{"name": name, "conditions": conditions}]
        headers = {"Zotero-Write-Token": token()}
        headers.update(self.default_headers())
        req = requests.post(
            url=self.endpoint
            + "/{t}/{u}/searches".format(t=self.library_type, u=self.library_id),
            headers=headers,
            data=json.dumps(payload),
        )
        self.request = req
        try:
            req.raise_for_status()
        except requests.exceptions.HTTPError:
            error_handler(req)
        return req.json()

Response: Create a saved search for the given name and conditions.


Instruction:
Given the following Python 3 function, write the documentation
def delete_saved_search(self, keys):
        headers = {"Zotero-Write-Token": token()}
        headers.update(self.default_headers())
        req = requests.delete(
            url=self.endpoint
            + "/{t}/{u}/searches".format(t=self.library_type, u=self.library_id),
            headers=headers,
            params={"searchKey": ",".join(keys)},
        )
        self.request = req
        try:
            req.raise_for_status()
        except requests.exceptions.HTTPError:
            error_handler(req)
        return req.status_code

Response: Delete one or more saved searches by passing a list of one or more unique search keys


Instruction:
Can you implement a function in Python 3 that
uploads files to the already created attachments

Response:
def upload_attachments(self, attachments, parentid=None, basedir=None):
        """Upload files to the already created (but never uploaded) attachments"""
        return Zupload(self, attachments, parentid, basedir=basedir).upload()


Instruction:
Can you implement a function in Python 3 that
adds one or more tags to an item and updates it on the server

Response:
def add_tags(self, item, *tags):
        """
        Add one or more tags to a retrieved item,
        then update it on the server
        Accepts a dict, and one or more tags to add to it
        Returns the updated item from the server
        """
        # Make sure there's a tags field, or add one
        try:
            assert item["data"]["tags"]
        except AssertionError:
            item["data"]["tags"] = list()
        for tag in tags:
            item["data"]["tags"].append({"tag": "%s" % tag})
        # make sure everything's OK
        assert self.check_items([item])
        return self.update_item(item)


Instruction:
How would you implement a function in Python 3 that
checks that the items to be created contain no invalid dict keys.

Response:
def check_items(self, items):
        """
        Check that items to be created contain no invalid dict keys
        Accepts a single argument: a list of one or more dicts
        The retrieved fields are cached and re-used until a 304 call fails
        """
        # check for a valid cached version
        if self.templates.get("item_fields") and not self._updated(
            "/itemFields", self.templates["item_fields"], "item_fields"
        ):
            template = set(t["field"] for t in self.templates["item_fields"]["tmplt"])
        else:
            template = set(t["field"] for t in self.item_fields())
        # add fields we know to be OK
        template = template | set(
            [
                "path",
                "tags",
                "notes",
                "itemType",
                "creators",
                "mimeType",
                "linkMode",
                "note",
                "charset",
                "dateAdded",
                "version",
                "collections",
                "dateModified",
                "relations",
                #  attachment items
                "parentItem",
                "mtime",
                "contentType",
                "md5",
                "filename",
            ]
        )
        template = template | set(self.temp_keys)
        for pos, item in enumerate(items):
            if set(item) == set(["links", "library", "version", "meta", "key", "data"]):
                # we have an item that was retrieved from the API
                item = item["data"]
            to_check = set(i for i in list(item.keys()))
            difference = to_check.difference(template)
            if difference:
                raise ze.InvalidItemFields(
                    "Invalid keys present in item %s: %s"
                    % (pos + 1, " ".join(i for i in difference))
                )
        return items


Instruction:
How would you explain what the following Python 3 function does
def fields_types(self, tname, qstring, itemtype):
        # check for a valid cached version
        template_name = tname + itemtype
        query_string = qstring.format(i=itemtype)
        if self.templates.get(template_name) and not self._updated(
            query_string, self.templates[template_name], template_name
        ):
            return self.templates[template_name]["tmplt"]
        # otherwise perform a normal request and cache the response
        retrieved = self._retrieve_data(query_string)
        return self._cache(retrieved, template_name)

Response: Retrieve item fields or creator types


Instruction:
Create a Python 3 function for
getting all available item fields

Response:
def item_fields(self):
        """ Get all available item fields
        """
        # Check for a valid cached version
        if self.templates.get("item_fields") and not self._updated(
            "/itemFields", self.templates["item_fields"], "item_fields"
        ):
            return self.templates["item_fields"]["tmplt"]
        query_string = "/itemFields"
        # otherwise perform a normal request and cache the response
        retrieved = self._retrieve_data(query_string)
        return self._cache(retrieved, "item_fields")