Instruction:
Create a Python 3 function to
build a binary distribution archive from an unpacked source distribution.

Response:
def build_binary_dist(self, requirement):
        """
        Build a binary distribution archive from an unpacked source distribution.

        :param requirement: A :class:`.Requirement` object.
        :returns: The pathname of a binary distribution archive (a string).
        :raises: :exc:`.BinaryDistributionError` when the original command
                and the fall back both fail to produce a binary distribution
                archive.

        This method uses the following command to build binary distributions:

        .. code-block:: sh

           $ python setup.py bdist_dumb --format=tar

        This command can fail for two main reasons:

        1. The package is missing binary dependencies.
        2. The ``setup.py`` script doesn't (properly) implement ``bdist_dumb``
           binary distribution format support.

        The first case is dealt with in :func:`get_binary_dist()`. To deal
        with the second case this method falls back to the following command:

        .. code-block:: sh

           $ python setup.py bdist

        This fall back is almost never needed, but there are Python packages
        out there which require this fall back (this method was added because
        the installation of ``Paver==1.2.3`` failed, see `issue 37`_ for
        details about that).

        .. _issue 37: https://github.com/paylogic/pip-accel/issues/37
        """
        try:
            return self.build_binary_dist_helper(requirement, ['bdist_dumb', '--format=tar'])
        except (BuildFailed, NoBuildOutput):
            logger.warning("Build of %s failed, falling back to alternative method ..", requirement)
            return self.build_binary_dist_helper(requirement, ['bdist', '--formats=gztar'])


Instruction:
Write a Python 3 function that can
build a binary distribution from an unpacked source distribution.

Response:
def build_binary_dist_helper(self, requirement, setup_command):
        """
        Convert an unpacked source distribution to a binary distribution.

        :param requirement: A :class:`.Requirement` object.
        :param setup_command: A list of strings with the arguments to
                              ``setup.py``.
        :returns: The pathname of the resulting binary distribution (a string).
        :raises: :exc:`.BuildFailed` when the build reports an error (e.g.
                 because of missing binary dependencies like system
                 libraries).
        :raises: :exc:`.NoBuildOutput` when the build does not produce the
                 expected binary distribution archive.
        """
        build_timer = Timer()
        # Make sure the source distribution contains a setup script.
        setup_script = os.path.join(requirement.source_directory, 'setup.py')
        if not os.path.isfile(setup_script):
            msg = "Directory %s (%s %s) doesn't contain a source distribution!"
            raise InvalidSourceDistribution(msg % (requirement.source_directory, requirement.name, requirement.version))
        # Let the user know what's going on.
        build_text = "Building %s binary distribution" % requirement
        logger.info("%s ..", build_text)
        # Cleanup previously generated distributions.
        dist_directory = os.path.join(requirement.source_directory, 'dist')
        if os.path.isdir(dist_directory):
            logger.debug("Cleaning up previously generated distributions in %s ..", dist_directory)
            shutil.rmtree(dist_directory)
        # Let the user know (approximately) which command is being executed
        # (I don't think it's necessary to show them the nasty details :-).
        logger.debug("Executing external command: %s",
                     ' '.join(map(pipes.quote, [self.config.python_executable, 'setup.py'] + setup_command)))
        # Compose the command line needed to build the binary distribution.
        # This nasty command line forces the use of setuptools (instead of
        # distutils) just like pip does. This will cause the `*.egg-info'
        # metadata to be written to a directory instead of a file, which
        # (amongst other things) enables tracking of installed files.
        command_line = [
            self.config.python_executable, '-c',
            ';'.join([
                'import setuptools',
                '__file__=%r' % setup_script,
                r"exec(compile(open(__file__).read().replace('\r\n', '\n'), __file__, 'exec'))",
            ])
        ] + setup_command
        # Redirect all output of the build to a temporary file.
        fd, temporary_file = tempfile.mkstemp()
        try:
            # Start the build.
            build = subprocess.Popen(command_line, cwd=requirement.source_directory, stdout=fd, stderr=fd)
            # Wait for the build to finish and provide feedback to the user in the mean time.
            spinner = Spinner(label=build_text, timer=build_timer)
            while build.poll() is None:
                spinner.step()
                # Don't tax the CPU too much.
                time.sleep(0.2)
            spinner.clear()
            # Make sure the build succeeded and produced a binary distribution archive.
            try:
                # If the build reported an error we'll try to provide the user with
                # some hints about what went wrong.
                if build.returncode != 0:
                    raise BuildFailed("Failed to build {name} ({version}) binary distribution!",
                                      name=requirement.name, version=requirement.version)
                # Check if the build created the `dist' directory (the os.listdir()
                # call below will raise an exception if we don't check for this).
                if not os.path.isdir(dist_directory):
                    raise NoBuildOutput("Build of {name} ({version}) did not produce a binary distribution archive!",
                                        name=requirement.name, version=requirement.version)
                # Check if we can find the binary distribution archive.
                filenames = os.listdir(dist_directory)
                if len(filenames) != 1:
                    variables = dict(name=requirement.name,
                                     version=requirement.version,
                                     filenames=concatenate(sorted(filenames)))
                    raise NoBuildOutput("""
                        Build of {name} ({version}) produced more than one
                        distribution archive! (matches: {filenames})
                    """, **variables)
            except Exception as e:
                # Decorate the exception with the output of the failed build.
                with open(temporary_file) as handle:
                    build_output = handle.read()
                enhanced_message = compact("""
                    {message}

                    Please check the build output because it will probably
                    provide a hint about what went wrong.

                    Build output:

                    {output}
                """, message=e.args[0], output=build_output.strip())
                e.args = (enhanced_message,)
                raise
            logger.info("Finished building %s in %s.", requirement.name, build_timer)
            return os.path.join(dist_directory, filenames[0])
        finally:
            # Close file descriptor before removing the temporary file.
            # Without closing Windows is complaining that the file cannot
            # be removed because it is used by another process.
            os.close(fd)
            os.unlink(temporary_file)


Instruction:
Write a Python 3 function for
transforming a binary distribution archive into a form that can be cached for future use.

Response:
def transform_binary_dist(self, archive_path):
        """
        Transform binary distributions into a form that can be cached for future use.

        :param archive_path: The pathname of the original binary distribution archive.
        :returns: An iterable of tuples with two values each:

                  1. A :class:`tarfile.TarInfo` object.
                  2. A file-like object.

        This method transforms a binary distribution archive created by
        :func:`build_binary_dist()` into a form that can be cached for future
        use. This comes down to making the pathnames inside the archive
        relative to the `prefix` that the binary distribution was built for.
        """
        # Copy the tar archive file by file so we can rewrite the pathnames.
        logger.debug("Transforming binary distribution: %s.", archive_path)
        archive = tarfile.open(archive_path, 'r')
        for member in archive.getmembers():
            # Some source distribution archives on PyPI that are distributed as ZIP
            # archives contain really weird permissions: the world readable bit is
            # missing. I've encountered this with the httplib2 (0.9) and
            # google-api-python-client (1.2) packages. I assume this is a bug of
            # some kind in the packaging process on "their" side.
            if member.mode & stat.S_IXUSR:
                # If the owner has execute permissions we'll give everyone read and
                # execute permissions (only the owner gets write permissions).
                member.mode = 0o755
            else:
                # If the owner doesn't have execute permissions we'll give everyone
                # read permissions (only the owner gets write permissions).
                member.mode = 0o644
            # In my testing the `dumb' tar files created with the `python
            # setup.py bdist' and `python setup.py bdist_dumb' commands contain
            # pathnames that are relative to `/' in one way or another:
            #
            #  - In almost all cases the pathnames look like this:
            #
            #      ./home/peter/.virtualenvs/pip-accel/lib/python2.7/site-packages/pip_accel/__init__.py
            #
            #  - After working on pip-accel for several years I encountered
            #    a pathname like this (Python 2.6 on Mac OS X 10.10.5):
            #
            #      Users/peter/.virtualenvs/pip-accel/lib/python2.6/site-packages/pip_accel/__init__.py
            #
            # Both of the above pathnames are relative to `/' but in different
            # ways :-). The following normpath(join('/', ...))) pathname
            # manipulation logic is intended to handle both cases.
            original_pathname = member.name
            absolute_pathname = os.path.normpath(os.path.join('/', original_pathname))
            if member.isdev():
                logger.warn("Ignoring device file: %s.", absolute_pathname)
            elif not member.isdir():
                modified_pathname = os.path.relpath(absolute_pathname, self.config.install_prefix)
                if os.path.isabs(modified_pathname):
                    logger.warn("Failed to transform pathname in binary distribution"
                                " to relative path! (original: %r, modified: %r)",
                                original_pathname, modified_pathname)
                else:
                    # Rewrite /usr/local to /usr (same goes for all prefixes of course).
                    modified_pathname = re.sub('^local/', '', modified_pathname)
                    # Rewrite /dist-packages/ to /site-packages/. For details see
                    # https://wiki.debian.org/Python#Deviations_from_upstream.
                    if self.config.on_debian:
                        modified_pathname = modified_pathname.replace('/dist-packages/', '/site-packages/')
                    # Enable operators to debug the transformation process.
                    logger.debug("Transformed %r -> %r.", original_pathname, modified_pathname)
                    # Get the file data from the input archive.
                    handle = archive.extractfile(original_pathname)
                    # Yield the modified metadata and a handle to the data.
                    member.name = modified_pathname
                    yield member, handle
        archive.close()


Instruction:
Write a Python 3 function that can
install a binary distribution into the given prefix. :param members: An iterable of tuples with two values each: 1. A :class:`tarfile.TarInfo` object. 2. A file-like object. :param prefix: The "prefix" under which the requirements should be installed. This will be a pathname like ``/usr``, ``/usr/local`` or the pathname of a virtual environment. Defaults to :attr:`.Config.install_prefix`. :param python: The pathname of the Python executable to use in the shebang line of all executable Python scripts inside the binary distribution. Defaults to :attr:`.Config.python_executable`. :param virtualenv_compatible: Whether to enable workarounds to make the resulting filenames compatible with virtual environments (defaults to :data:`True`). :param track_installed_files: If this is :data:`True` (not the default for this method because of backwards compatibility) pip-accel will create ``installed-files.txt`` as required by pip to properly uninstall packages. This method installs a binary distribution created by :class:`build_binary_dist()` into the given prefix (a directory like ``/usr``, ``/usr/local`` or a virtual environment).

Response:
def install_binary_dist(self, members, virtualenv_compatible=True, prefix=None,
                            python=None, track_installed_files=False):
        """
        Install a binary distribution into the given prefix.

        :param members: An iterable of tuples with two values each:

                        1. A :class:`tarfile.TarInfo` object.
                        2. A file-like object.
        :param prefix: The "prefix" under which the requirements should be
                       installed. This will be a pathname like ``/usr``,
                       ``/usr/local`` or the pathname of a virtual environment.
                       Defaults to :attr:`.Config.install_prefix`.
        :param python: The pathname of the Python executable to use in the shebang
                       line of all executable Python scripts inside the binary
                       distribution. Defaults to :attr:`.Config.python_executable`.
        :param virtualenv_compatible: Whether to enable workarounds to make the
                                      resulting filenames compatible with
                                      virtual environments (defaults to
                                      :data:`True`).
        :param track_installed_files: If this is :data:`True` (not the default for
                                      this method because of backwards
                                      compatibility) pip-accel will create
                                      ``installed-files.txt`` as required by
                                      pip to properly uninstall packages.

        This method installs a binary distribution created by
        :class:`build_binary_dist()` into the given prefix (a directory like
        ``/usr``, ``/usr/local`` or a virtual environment).
        """
        # TODO This is quite slow for modules like Django. Speed it up! Two choices:
        #  1. Run the external tar program to unpack the archive. This will
        #     slightly complicate the fixing up of hashbangs.
        #  2. Using links? The plan: We can maintain a "seed" environment under
        #     $PIP_ACCEL_CACHE and use symbolic and/or hard links to populate other
        #     places based on the "seed" environment.
        module_search_path = set(map(os.path.normpath, sys.path))
        prefix = os.path.normpath(prefix or self.config.install_prefix)
        python = os.path.normpath(python or self.config.python_executable)
        installed_files = []
        for member, from_handle in members:
            pathname = member.name
            if virtualenv_compatible:
                # Some binary distributions include C header files (see for example
                # the greenlet package) however the subdirectory of include/ in a
                # virtual environment is a symbolic link to a subdirectory of
                # /usr/include/ so we should never try to install C header files
                # inside the directory pointed to by the symbolic link. Instead we
                # implement the same workaround that pip uses to avoid this
                # problem.
                pathname = re.sub('^include/', 'include/site/', pathname)
            if self.config.on_debian and '/site-packages/' in pathname:
                # On Debian based system wide Python installs the /site-packages/
                # directory is not in Python's module search path while
                # /dist-packages/ is. We try to be compatible with this.
                match = re.match('^(.+?)/site-packages', pathname)
                if match:
                    site_packages = os.path.normpath(os.path.join(prefix, match.group(0)))
                    dist_packages = os.path.normpath(os.path.join(prefix, match.group(1), 'dist-packages'))
                    if dist_packages in module_search_path and site_packages not in module_search_path:
                        pathname = pathname.replace('/site-packages/', '/dist-packages/')
            pathname = os.path.join(prefix, pathname)
            if track_installed_files:
                # Track the installed file's absolute pathname.
                installed_files.append(pathname)
            directory = os.path.dirname(pathname)
            if not os.path.isdir(directory):
                logger.debug("Creating directory: %s ..", directory)
                makedirs(directory)
            logger.debug("Creating file: %s ..", pathname)
            with open(pathname, 'wb') as to_handle:
                contents = from_handle.read()
                if contents.startswith(b'#!/'):
                    contents = self.fix_hashbang(contents, python)
                to_handle.write(contents)
            os.chmod(pathname, member.mode)
        if track_installed_files:
            self.update_installed_files(installed_files)


Instruction:
Can you generate the documentation for the following Python 3 function
def fix_hashbang(self, contents, python):
        lines = contents.splitlines()
        if lines:
            hashbang = lines[0]
            # Get the base name of the command in the hashbang.
            executable = os.path.basename(hashbang)
            # Deal with hashbangs like `#!/usr/bin/env python'.
            executable = re.sub(b'^env ', b'', executable)
            # Only rewrite hashbangs that actually involve Python.
            if re.match(b'^python(\\d+(\\.\\d+)*)?$', executable):
                lines[0] = b'#!' + python.encode('ascii')
                logger.debug("Rewriting hashbang %r to %r!", hashbang, lines[0])
                contents = b'\n'.join(lines)
        return contents

Response: Rewrite hashbangs_ to use the correct Python executable.


Instruction:
How would you implement a function in Python 3 that
updates the list of installed files by pip.

Response:
def update_installed_files(self, installed_files):
        """
        Track the files installed by a package so pip knows how to remove the package.

        This method is used by :func:`install_binary_dist()` (which collects
        the list of installed files for :func:`update_installed_files()`).

        :param installed_files: A list of absolute pathnames (strings) with the
                                files that were just installed.
        """
        # Find the *.egg-info directory where installed-files.txt should be created.
        pkg_info_files = [fn for fn in installed_files if fnmatch.fnmatch(fn, '*.egg-info/PKG-INFO')]
        # I'm not (yet) sure how reliable the above logic is, so for now
        # I'll err on the side of caution and only act when the results
        # seem to be reliable.
        if len(pkg_info_files) != 1:
            logger.warning("Not tracking installed files (couldn't reliably determine *.egg-info directory)")
        else:
            egg_info_directory = os.path.dirname(pkg_info_files[0])
            installed_files_path = os.path.join(egg_info_directory, 'installed-files.txt')
            logger.debug("Tracking installed files in %s ..", installed_files_path)
            with open(installed_files_path, 'w') as handle:
                for pathname in installed_files:
                    handle.write('%s\n' % os.path.relpath(pathname, egg_info_directory))


Instruction:
Make a summary of the following Python 3 code
def load_configuration_file(self, configuration_file):
        configuration_file = parse_path(configuration_file)
        logger.debug("Loading configuration file: %s", configuration_file)
        parser = configparser.RawConfigParser()
        files_loaded = parser.read(configuration_file)
        if len(files_loaded) != 1:
            msg = "Failed to load configuration file! (%s)"
            raise Exception(msg % configuration_file)
        elif not parser.has_section('pip-accel'):
            msg = "Missing 'pip-accel' section in configuration file! (%s)"
            raise Exception(msg % configuration_file)
        else:
            self.configuration.update(parser.items('pip-accel'))

Response: Load the configuration from a configuration file.


Instruction:
Create a Python 3 function to
get the value of a configuration option in the configuration file.

Response:
def get(self, property_name=None, environment_variable=None, configuration_option=None, default=None):
        """
        Internal shortcut to get a configuration option's value.

        :param property_name: The name of the property that users can set on
                              the :class:`Config` class (a string).
        :param environment_variable: The name of the environment variable (a
                                     string).
        :param configuration_option: The name of the option in the
                                     configuration file (a string).
        :param default: The default value.
        :returns: The value of the environment variable or configuration file
                  option or the default value.
        """
        if self.overrides.get(property_name) is not None:
            return self.overrides[property_name]
        elif environment_variable and self.environment.get(environment_variable):
            return self.environment[environment_variable]
        elif self.configuration.get(configuration_option) is not None:
            return self.configuration[configuration_option]
        else:
            return default


Instruction:
Here you have a function in Python 3, explain what it does
def source_index(self):
        return self.get(property_name='source_index',
                        default=os.path.join(self.data_directory, 'sources'))

Response: The absolute pathname of pip - accel s source index directory.


Instruction:
How would you implement a function in Python 3 that
returns the absolute pathname of the directory where pip - accel s data files are stored.

Response:
def data_directory(self):
        """
        The absolute pathname of the directory where pip-accel's data files are stored (a string).

        - Environment variable: ``$PIP_ACCEL_CACHE``
        - Configuration option: ``data-directory``
        - Default: ``/var/cache/pip-accel`` if running as ``root``, ``~/.pip-accel`` otherwise
        """
        return expand_path(self.get(property_name='data_directory',
                                    environment_variable='PIP_ACCEL_CACHE',
                                    configuration_option='data-directory',
                                    default='/var/cache/pip-accel' if is_root() else '~/.pip-accel'))


Instruction:
How would you implement a function in Python 3 that
returns the absolute pathname of the installation prefix to use for this system.

Response:
def install_prefix(self):
        """
        The absolute pathname of the installation prefix to use (a string).

        This property is based on :data:`sys.prefix` except that when
        :data:`sys.prefix` is ``/usr`` and we're running on a Debian derived
        system ``/usr/local`` is used instead.

        The reason for this is that on Debian derived systems only apt (dpkg)
        should be allowed to touch files in ``/usr/lib/pythonX.Y/dist-packages``
        and ``python setup.py install`` knows this (see the ``posix_local``
        installation scheme in ``/usr/lib/pythonX.Y/sysconfig.py`` on Debian
        derived systems). Because pip-accel replaces ``python setup.py
        install`` it has to replicate this logic. Inferring all of this from
        the :mod:`sysconfig` module would be nice but that module wasn't
        available in Python 2.6.
        """
        return self.get(property_name='install_prefix',
                        default='/usr/local' if sys.prefix == '/usr' and self.on_debian else sys.prefix)


Instruction:
How would you explain what the following Python 3 function does
def auto_install(self):
        value = self.get(property_name='auto_install',
                         environment_variable='PIP_ACCEL_AUTO_INSTALL',
                         configuration_option='auto-install')
        if value is not None:
            return coerce_boolean(value)

Response: Returns a boolean value indicating whether automatic installation of missing system packages is enabled.


Instruction:
Can you generate the documentation for the following Python 3 function
def trust_mod_times(self):
        on_appveyor = coerce_boolean(os.environ.get('APPVEYOR', 'False'))
        return coerce_boolean(self.get(property_name='trust_mod_times',
                                       environment_variable='PIP_ACCEL_TRUST_MOD_TIMES',
                                       configuration_option='trust-mod-times',
                                       default=(not on_appveyor)))

Response: Determines whether to trust file modification times for cache invalidation.


Instruction:
Can you generate the documentation for the following Python 3 function
def s3_cache_readonly(self):
        return coerce_boolean(self.get(property_name='s3_cache_readonly',
                                       environment_variable='PIP_ACCEL_S3_READONLY',
                                       configuration_option='s3-readonly',
                                       default=False))

Response: Determines if the Amazon S3 bucket is considered read only.


Instruction:
Write a Python 3 function that can
get the socket timeout in seconds for connections to Amazon S3.

Response:
def s3_cache_timeout(self):
        """
        The socket timeout in seconds for connections to Amazon S3 (an integer).

        This value is injected into Boto's configuration to override the
        default socket timeout used for connections to Amazon S3.

        - Environment variable: ``$PIP_ACCEL_S3_TIMEOUT``
        - Configuration option: ``s3-timeout``
        - Default: ``60`` (`Boto's default`_)

        .. _Boto's default: http://boto.readthedocs.org/en/latest/boto_config_tut.html
        """
        value = self.get(property_name='s3_cache_timeout',
                         environment_variable='PIP_ACCEL_S3_TIMEOUT',
                         configuration_option='s3-timeout')
        try:
            n = int(value)
            if n >= 0:
                return n
        except:
            return 60


Instruction:
Implement a function in Python 3 to
download a distribution archive from the configured Amazon S3 bucket.

Response:
def get(self, filename):
        """
        Download a distribution archive from the configured Amazon S3 bucket.

        :param filename: The filename of the distribution archive (a string).
        :returns: The pathname of a distribution archive on the local file
                  system or :data:`None`.
        :raises: :exc:`.CacheBackendError` when any underlying method fails.
        """
        timer = Timer()
        self.check_prerequisites()
        with PatchedBotoConfig():
            # Check if the distribution archive is available.
            raw_key = self.get_cache_key(filename)
            logger.info("Checking if distribution archive is available in S3 bucket: %s", raw_key)
            key = self.s3_bucket.get_key(raw_key)
            if key is None:
                logger.debug("Distribution archive is not available in S3 bucket.")
            else:
                # Download the distribution archive to the local binary index.
                # TODO Shouldn't this use LocalCacheBackend.put() instead of
                #      implementing the same steps manually?!
                logger.info("Downloading distribution archive from S3 bucket ..")
                file_in_cache = os.path.join(self.config.binary_cache, filename)
                makedirs(os.path.dirname(file_in_cache))
                with AtomicReplace(file_in_cache) as temporary_file:
                    key.get_contents_to_filename(temporary_file)
                logger.debug("Finished downloading distribution archive from S3 bucket in %s.", timer)
                return file_in_cache


Instruction:
Here you have a function in Python 3, explain what it does
def put(self, filename, handle):
        if self.config.s3_cache_readonly:
            logger.info('Skipping upload to S3 bucket (using S3 in read only mode).')
        else:
            timer = Timer()
            self.check_prerequisites()
            with PatchedBotoConfig():
                from boto.s3.key import Key
                raw_key = self.get_cache_key(filename)
                logger.info("Uploading distribution archive to S3 bucket: %s", raw_key)
                key = Key(self.s3_bucket)
                key.key = raw_key
                try:
                    key.set_contents_from_file(handle)
                except Exception as e:
                    logger.info("Encountered error writing to S3 bucket, "
                                "falling back to read only mode (exception: %s)", e)
                    self.config.s3_cache_readonly = True
                else:
                    logger.info("Finished uploading distribution archive to S3 bucket in %s.", timer)

Response: Uploads a distribution archive to the configured Amazon S3 bucket.


Instruction:
Can you tell what is the following Python 3 function doing
def s3_bucket(self):
        if not hasattr(self, 'cached_bucket'):
            self.check_prerequisites()
            with PatchedBotoConfig():
                from boto.exception import BotoClientError, BotoServerError, S3ResponseError
                # The following try/except block translates unexpected exceptions
                # raised by Boto into a CacheBackendError exception.
                try:
                    # The following try/except block handles the expected exception
                    # raised by Boto when an Amazon S3 bucket does not exist.
                    try:
                        logger.debug("Connecting to Amazon S3 bucket: %s", self.config.s3_cache_bucket)
                        self.cached_bucket = self.s3_connection.get_bucket(self.config.s3_cache_bucket)
                    except S3ResponseError as e:
                        if e.status == 404 and self.config.s3_cache_create_bucket:
                            logger.info("Amazon S3 bucket doesn't exist yet, creating it now: %s",
                                        self.config.s3_cache_bucket)
                            self.s3_connection.create_bucket(self.config.s3_cache_bucket)
                            self.cached_bucket = self.s3_connection.get_bucket(self.config.s3_cache_bucket)
                        else:
                            # Don't swallow exceptions we can't handle.
                            raise
                except (BotoClientError, BotoServerError):
                    raise CacheBackendError("""
                        Failed to connect to the configured Amazon S3 bucket
                        {bucket}! Are you sure the bucket exists and is accessible
                        using the provided credentials? The Amazon S3 cache backend
                        will be disabled for now.
                    """, bucket=repr(self.config.s3_cache_bucket))
        return self.cached_bucket

Response: Connect to the user defined Amazon S3 bucket.


Instruction:
Write a Python 3 function for
connecting to the Amazon S3 API.

Response:
def s3_connection(self):
        """
        Connect to the Amazon S3 API.

        If the connection attempt fails because Boto can't find credentials the
        attempt is retried once with an anonymous connection.

        Called on demand by :attr:`s3_bucket`.

        :returns: A :class:`boto.s3.connection.S3Connection` object.
        :raises: :exc:`.CacheBackendError` when the connection to the Amazon
                 S3 API fails.
        """
        if not hasattr(self, 'cached_connection'):
            self.check_prerequisites()
            with PatchedBotoConfig():
                import boto
                from boto.exception import BotoClientError, BotoServerError, NoAuthHandlerFound
                from boto.s3.connection import S3Connection, SubdomainCallingFormat, OrdinaryCallingFormat
                try:
                    # Configure the number of retries and the socket timeout used
                    # by Boto. Based on the snippet given in the following email:
                    # https://groups.google.com/d/msg/boto-users/0osmP0cUl5Y/X4NdlMGWKiEJ
                    if not boto.config.has_section(BOTO_CONFIG_SECTION):
                        boto.config.add_section(BOTO_CONFIG_SECTION)
                    boto.config.set(BOTO_CONFIG_SECTION,
                                    BOTO_CONFIG_NUM_RETRIES_OPTION,
                                    str(self.config.s3_cache_retries))
                    boto.config.set(BOTO_CONFIG_SECTION,
                                    BOTO_CONFIG_SOCKET_TIMEOUT_OPTION,
                                    str(self.config.s3_cache_timeout))
                    logger.debug("Connecting to Amazon S3 API ..")
                    endpoint = urlparse(self.config.s3_cache_url)
                    host, _, port = endpoint.netloc.partition(':')
                    kw = dict(
                        host=host,
                        port=int(port) if port else None,
                        is_secure=(endpoint.scheme == 'https'),
                        calling_format=(SubdomainCallingFormat() if host == S3Connection.DefaultHost
                                        else OrdinaryCallingFormat()),
                    )
                    try:
                        self.cached_connection = S3Connection(**kw)
                    except NoAuthHandlerFound:
                        logger.debug("Amazon S3 API credentials missing, retrying with anonymous connection ..")
                        self.cached_connection = S3Connection(anon=True, **kw)
                except (BotoClientError, BotoServerError):
                    raise CacheBackendError("""
                        Failed to connect to the Amazon S3 API! Most likely your
                        credentials are not correctly configured. The Amazon S3
                        cache backend will be disabled for now.
                    """)
        return self.cached_connection


Instruction:
Explain what the following Python 3 code does
def get(self, section, name, default=None, **kw):
        try:
            return self.unbound_method(self.instance, section, name, **kw)
        except Exception:
            return default

Response: Replacement for boto. pyami. config. Config. get


Instruction:
Implement a Python 3 function for
returning a list of the pathnames of the source distribution archives that this requirement is related to.

Response:
def related_archives(self):
        """
        The pathnames of the source distribution(s) for this requirement (a list of strings).

        .. note:: This property is very new in pip-accel and its logic may need
                  some time to mature. For now any misbehavior by this property
                  shouldn't be too much of a problem because the pathnames
                  reported by this property are only used for cache
                  invalidation (see the :attr:`last_modified` and
                  :attr:`checksum` properties).
        """
        # Escape the requirement's name for use in a regular expression.
        name_pattern = escape_name(self.name)
        # Escape the requirement's version for in a regular expression.
        version_pattern = re.escape(self.version)
        # Create a regular expression that matches any of the known source
        # distribution archive extensions.
        extension_pattern = '|'.join(re.escape(ext) for ext in ARCHIVE_EXTENSIONS if ext != '.whl')
        # Compose the regular expression pattern to match filenames of source
        # distribution archives in the local source index directory.
        pattern = '^%s-%s(%s)$' % (name_pattern, version_pattern, extension_pattern)
        # Compile the regular expression for case insensitive matching.
        compiled_pattern = re.compile(pattern, re.IGNORECASE)
        # Find the matching source distribution archives.
        return [os.path.join(self.config.source_index, fn)
                for fn in os.listdir(self.config.source_index)
                if compiled_pattern.match(fn)]


Instruction:
Given the following Python 3 function, write the documentation
def last_modified(self):
        mtimes = list(map(os.path.getmtime, self.related_archives))
        return max(mtimes) if mtimes else time.time()

Response: Returns the last modified time of the binary containing this requirement s source distribution archive.


Instruction:
Can you create a Python 3 function that
determines if the given requirement is a wheel.

Response:
def is_wheel(self):
        """
        :data:`True` when the requirement is a wheel, :data:`False` otherwise.

        .. note:: To my surprise it seems to be non-trivial to determine
                  whether a given :class:`pip.req.InstallRequirement` object
                  produced by pip's internal Python API concerns a source
                  distribution or a wheel distribution.

                  There's a :class:`pip.req.InstallRequirement.is_wheel`
                  property but I'm currently looking at a wheel distribution
                  whose ``is_wheel`` property returns :data:`None`, apparently
                  because the requirement's ``url`` property is also :data:`None`.

                  Whether this is an obscure implementation detail of pip or
                  caused by the way pip-accel invokes pip, I really can't tell
                  (yet).
        """
        probably_sdist = os.path.isfile(os.path.join(self.source_directory, 'setup.py'))
        probably_wheel = len(glob.glob(os.path.join(self.source_directory, '*.dist-info', 'WHEEL'))) > 0
        if probably_wheel and not probably_sdist:
            return True
        elif probably_sdist and not probably_wheel:
            return False
        elif probably_sdist and probably_wheel:
            variables = dict(requirement=self.setuptools_requirement,
                             directory=self.source_directory)
            raise UnknownDistributionFormat("""
                The unpacked distribution of {requirement} in {directory} looks
                like a source distribution and a wheel distribution, I'm
                confused!
            """, **variables)
        else:
            variables = dict(requirement=self.setuptools_requirement,
                             directory=self.source_directory)
            raise UnknownDistributionFormat("""
                The unpacked distribution of {requirement} in {directory}
                doesn't look like a source distribution and also doesn't look
                like a wheel distribution, I'm confused!
            """, **variables)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def wheel_metadata(self):
        if not self.is_wheel:
            raise TypeError("Requirement is not a wheel distribution!")
        for distribution in find_distributions(self.source_directory):
            return distribution
        msg = "pkg_resources didn't find a wheel distribution in %s!"
        raise Exception(msg % self.source_directory)

Response: Get the distribution metadata of an unpacked wheel distribution.


Instruction:
Write a Python 3 script for
validating that the virtual environment is correct.

Response:
def validate_environment(self):
        """
        Make sure :data:`sys.prefix` matches ``$VIRTUAL_ENV`` (if defined).

        This may seem like a strange requirement to dictate but it avoids hairy
        issues like `documented here <https://github.com/paylogic/pip-accel/issues/5>`_.

        The most sneaky thing is that ``pip`` doesn't have this problem
        (de-facto) because ``virtualenv`` copies ``pip`` wherever it goes...
        (``pip-accel`` on the other hand has to be installed by the user).
        """
        environment = os.environ.get('VIRTUAL_ENV')
        if environment:
            if not same_directories(sys.prefix, environment):
                raise EnvironmentMismatchError("""
                    You are trying to install packages in environment #1 which
                    is different from environment #2 where pip-accel is
                    installed! Please install pip-accel under environment #1 to
                    install packages there.

                    Environment #1: {environment} (defined by $VIRTUAL_ENV)

                    Environment #2: {prefix} (Python's installation prefix)
                """, environment=environment, prefix=sys.prefix)


Instruction:
Given the following Python 3 function, write the documentation
def initialize_directories(self):
        makedirs(self.config.source_index)
        makedirs(self.config.eggs_cache)

Response: Automatically create local directories required by pip - accel.


Instruction:
How would you explain what the following Python 3 function does
def clean_source_index(self):
        cleanup_timer = Timer()
        cleanup_counter = 0
        for entry in os.listdir(self.config.source_index):
            pathname = os.path.join(self.config.source_index, entry)
            if os.path.islink(pathname) and not os.path.exists(pathname):
                logger.warn("Cleaning up broken symbolic link: %s", pathname)
                os.unlink(pathname)
                cleanup_counter += 1
        logger.debug("Cleaned up %i broken symbolic links from source index in %s.", cleanup_counter, cleanup_timer)

Response: This method cleans up broken symbolic links in the local source distribution index directory.


Instruction:
Write a Python 3 function that can
download unpack build and install the specified requirements.

Response:
def install_from_arguments(self, arguments, **kw):
        """
        Download, unpack, build and install the specified requirements.

        This function is a simple wrapper for :func:`get_requirements()`,
        :func:`install_requirements()` and :func:`cleanup_temporary_directories()`
        that implements the default behavior of the pip accelerator. If you're
        extending or embedding pip-accel you may want to call the underlying
        methods instead.

        If the requirement set includes wheels and ``setuptools >= 0.8`` is not
        yet installed, it will be added to the requirement set and installed
        together with the other requirement(s) in order to enable the usage of
        distributions installed from wheels (their metadata is different).

        :param arguments: The command line arguments to ``pip install ..`` (a
                          list of strings).
        :param kw: Any keyword arguments are passed on to
                   :func:`install_requirements()`.
        :returns: The result of :func:`install_requirements()`.
        """
        try:
            requirements = self.get_requirements(arguments, use_wheels=self.arguments_allow_wheels(arguments))
            have_wheels = any(req.is_wheel for req in requirements)
            if have_wheels and not self.setuptools_supports_wheels():
                logger.info("Preparing to upgrade to setuptools >= 0.8 to enable wheel support ..")
                requirements.extend(self.get_requirements(['setuptools >= 0.8']))
            if requirements:
                if '--user' in arguments:
                    from site import USER_BASE
                    kw.setdefault('prefix', USER_BASE)
                return self.install_requirements(requirements, **kw)
            else:
                logger.info("Nothing to do! (requirements already installed)")
                return 0
        finally:
            self.cleanup_temporary_directories()


Instruction:
How would you explain what the following Python 3 function does
def get_requirements(self, arguments, max_retries=None, use_wheels=False):
        arguments = self.decorate_arguments(arguments)
        # Demote hash sum mismatch log messages from CRITICAL to DEBUG (hiding
        # implementation details from users unless they want to see them).
        with DownloadLogFilter():
            with SetupRequiresPatch(self.config, self.eggs_links):
                # Use a new build directory for each run of get_requirements().
                self.create_build_directory()
                # Check whether -U or --upgrade was given.
                if any(match_option(a, '-U', '--upgrade') for a in arguments):
                    logger.info("Checking index(es) for new version (-U or --upgrade was given) ..")
                else:
                    # If -U or --upgrade wasn't given and all requirements can be
                    # satisfied using the archives in pip-accel's local source
                    # index we don't need pip to connect to PyPI looking for new
                    # versions (that will just slow us down).
                    try:
                        return self.unpack_source_dists(arguments, use_wheels=use_wheels)
                    except DistributionNotFound:
                        logger.info("We don't have all distribution archives yet!")
                # Get the maximum number of retries from the configuration if the
                # caller didn't specify a preference.
                if max_retries is None:
                    max_retries = self.config.max_retries
                # If not all requirements are available locally we use pip to
                # download the missing source distribution archives from PyPI (we
                # retry a couple of times in case pip reports recoverable
                # errors).
                for i in range(max_retries):
                    try:
                        return self.download_source_dists(arguments, use_wheels=use_wheels)
                    except Exception as e:
                        if i + 1 < max_retries:
                            # On all but the last iteration we swallow exceptions
                            # during downloading.
                            logger.warning("pip raised exception while downloading distributions: %s", e)
                        else:
                            # On the last iteration we don't swallow exceptions
                            # during downloading because the error reported by pip
                            # is the most sensible error for us to report.
                            raise
                    logger.info("Retrying after pip failed (%i/%i) ..", i + 1, max_retries)

Response: Get the requirements for the given list of source distribution archives.


Instruction:
Can you implement a function in Python 3 that
changes pathnames of local files into ``file://`` URLs with ``#md5=...`` fragments. :param arguments: The command line arguments to ``pip install ...`` (a list of strings). :returns: A copy of the command line arguments with pathnames of local files rewritten to ``file://`` URLs. When pip-accel calls pip to download missing distribution archives and the user specified the pathname of a local distribution archive on the command line, pip will (by default) *not* copy the archive into the download directory if an archive for the same package name and version is already present. This can lead to the confusing situation where the user specifies a local distribution archive to install, a different (older) archive for the same package and version is present in the download directory and `pip-accel` installs the older archive instead of the newer archive. To avoid this confusing behavior, the :func:`decorate_arguments()` method rewrites the command line arguments given to ``pip install`` so that pathnames of local archives are changed into ``file://`` URLs that include a fragment with the hash of the file's contents. Here's an example: - Local pathname: ``/tmp/pep8-1.6.3a0.tar.gz`` - File URL: ``file:///tmp/pep8-1.6.3a0.tar.gz#md5=19cbf0b633498ead63fb3c66e5f1caf6`` When pip fills the download directory and encounters a previously cached distribution archive it will check the hash, realize the contents have changed and replace the archive in the download directory.

Response:
def decorate_arguments(self, arguments):
        """
        Change pathnames of local files into ``file://`` URLs with ``#md5=...`` fragments.

        :param arguments: The command line arguments to ``pip install ...`` (a
                          list of strings).
        :returns: A copy of the command line arguments with pathnames of local
                  files rewritten to ``file://`` URLs.

        When pip-accel calls pip to download missing distribution archives and
        the user specified the pathname of a local distribution archive on the
        command line, pip will (by default) *not* copy the archive into the
        download directory if an archive for the same package name and
        version is already present.

        This can lead to the confusing situation where the user specifies a
        local distribution archive to install, a different (older) archive for
        the same package and version is present in the download directory and
        `pip-accel` installs the older archive instead of the newer archive.

        To avoid this confusing behavior, the :func:`decorate_arguments()`
        method rewrites the command line arguments given to ``pip install`` so
        that pathnames of local archives are changed into ``file://`` URLs that
        include a fragment with the hash of the file's contents. Here's an
        example:

        - Local pathname: ``/tmp/pep8-1.6.3a0.tar.gz``
        - File URL: ``file:///tmp/pep8-1.6.3a0.tar.gz#md5=19cbf0b633498ead63fb3c66e5f1caf6``

        When pip fills the download directory and encounters a previously
        cached distribution archive it will check the hash, realize the
        contents have changed and replace the archive in the download
        directory.
        """
        arguments = list(arguments)
        for i, value in enumerate(arguments):
            is_constraint_file = (i >= 1 and match_option(arguments[i - 1], '-c', '--constraint'))
            is_requirement_file = (i >= 1 and match_option(arguments[i - 1], '-r', '--requirement'))
            if not is_constraint_file and not is_requirement_file and os.path.isfile(value):
                arguments[i] = '%s#md5=%s' % (create_file_url(value), hash_files('md5', value))
        return arguments


Instruction:
Can you implement a function in Python 3 that
finds and unpack local source distributions and discover their metadata.

Response:
def unpack_source_dists(self, arguments, use_wheels=False):
        """
        Find and unpack local source distributions and discover their metadata.

        :param arguments: The command line arguments to ``pip install ...`` (a
                          list of strings).
        :param use_wheels: Whether pip and pip-accel are allowed to use wheels_
                           (:data:`False` by default for backwards compatibility
                           with callers that use pip-accel as a Python API).
        :returns: A list of :class:`pip_accel.req.Requirement` objects.
        :raises: Any exceptions raised by pip, for example
                 :exc:`pip.exceptions.DistributionNotFound` when not all
                 requirements can be satisfied.

        This function checks whether there are local source distributions
        available for all requirements, unpacks the source distribution
        archives and finds the names and versions of the requirements. By using
        the ``pip install --download`` command we avoid reimplementing the
        following pip features:

        - Parsing of ``requirements.txt`` (including recursive parsing).
        - Resolution of possibly conflicting pinned requirements.
        - Unpacking source distributions in multiple formats.
        - Finding the name & version of a given source distribution.
        """
        unpack_timer = Timer()
        logger.info("Unpacking distribution(s) ..")
        with PatchedAttribute(pip_install_module, 'PackageFinder', CustomPackageFinder):
            requirements = self.get_pip_requirement_set(arguments, use_remote_index=False, use_wheels=use_wheels)
            logger.info("Finished unpacking %s in %s.", pluralize(len(requirements), "distribution"), unpack_timer)
            return requirements


Instruction:
Can you generate the documentation for the following Python 3 function
def download_source_dists(self, arguments, use_wheels=False):
        download_timer = Timer()
        logger.info("Downloading missing distribution(s) ..")
        requirements = self.get_pip_requirement_set(arguments, use_remote_index=True, use_wheels=use_wheels)
        logger.info("Finished downloading distribution(s) in %s.", download_timer)
        return requirements

Response: Download missing source distributions.


Instruction:
Write a Python 3 script to
return a pip. req. RequirementSet object for the given pip arguments.

Response:
def get_pip_requirement_set(self, arguments, use_remote_index, use_wheels=False):
        """
        Get the unpacked requirement(s) specified by the caller by running pip.

        :param arguments: The command line arguments to ``pip install ...`` (a
                          list of strings).
        :param use_remote_index: A boolean indicating whether pip is allowed to
                                 connect to the main package index
                                 (http://pypi.python.org by default).
        :param use_wheels: Whether pip and pip-accel are allowed to use wheels_
                           (:data:`False` by default for backwards compatibility
                           with callers that use pip-accel as a Python API).
        :returns: A :class:`pip.req.RequirementSet` object created by pip.
        :raises: Any exceptions raised by pip.
        """
        # Compose the pip command line arguments. This is where a lot of the
        # core logic of pip-accel is hidden and it uses some esoteric features
        # of pip so this method is heavily commented.
        command_line = []
        # Use `--download' to instruct pip to download requirement(s) into
        # pip-accel's local source distribution index directory. This has the
        # following documented side effects (see `pip install --help'):
        #  1. It disables the installation of requirements (without using the
        #     `--no-install' option which is deprecated and slated for removal
        #     in pip 7.x).
        #  2. It ignores requirements that are already installed (because
        #     pip-accel doesn't actually need to re-install requirements that
        #     are already installed we will have work around this later, but
        #     that seems fairly simple to do).
        command_line.append('--download=%s' % self.config.source_index)
        # Use `--find-links' to point pip at pip-accel's local source
        # distribution index directory. This ensures that source distribution
        # archives are never downloaded more than once (regardless of the HTTP
        # cache that was introduced in pip 6.x).
        command_line.append('--find-links=%s' % create_file_url(self.config.source_index))
        # Use `--no-binary=:all:' to ignore wheel distributions by default in
        # order to preserve backwards compatibility with callers that expect a
        # requirement set consisting only of source distributions that can be
        # converted to `dumb binary distributions'.
        if not use_wheels and self.arguments_allow_wheels(arguments):
            command_line.append('--no-binary=:all:')
        # Use `--no-index' to force pip to only consider source distribution
        # archives contained in pip-accel's local source distribution index
        # directory. This enables pip-accel to ask pip "Can the local source
        # distribution index satisfy all requirements in the given requirement
        # set?" which enables pip-accel to keep pip off the internet unless
        # absolutely necessary :-).
        if not use_remote_index:
            command_line.append('--no-index')
        # Use `--no-clean' to instruct pip to unpack the source distribution
        # archives and *not* clean up the unpacked source distributions
        # afterwards. This enables pip-accel to replace pip's installation
        # logic with cached binary distribution archives.
        command_line.append('--no-clean')
        # Use `--build-directory' to instruct pip to unpack the source
        # distribution archives to a temporary directory managed by pip-accel.
        # We will clean up the build directory when we're done using the
        # unpacked source distributions.
        command_line.append('--build-directory=%s' % self.build_directory)
        # Append the user's `pip install ...' arguments to the command line
        # that we just assembled.
        command_line.extend(arguments)
        logger.info("Executing command: pip install %s", ' '.join(command_line))
        # Clear the build directory to prevent PreviousBuildDirError exceptions.
        self.clear_build_directory()
        # During the pip 6.x upgrade pip-accel switched to using `pip install
        # --download' which can produce an interactive prompt as described in
        # issue 51 [1]. The documented way [2] to get rid of this interactive
        # prompt is pip's --exists-action option, but due to what is most
        # likely a bug in pip this doesn't actually work. The environment
        # variable $PIP_EXISTS_ACTION does work however, so if the user didn't
        # set it we will set a reasonable default for them.
        # [1] https://github.com/paylogic/pip-accel/issues/51
        # [2] https://pip.pypa.io/en/latest/reference/pip.html#exists-action-option
        os.environ.setdefault('PIP_EXISTS_ACTION', 'w')
        # Initialize and run the `pip install' command.
        command = InstallCommand()
        opts, args = command.parse_args(command_line)
        if not opts.ignore_installed:
            # If the user didn't supply the -I, --ignore-installed option we
            # will forcefully disable the option. Refer to the documentation of
            # the AttributeOverrides class for further details.
            opts = AttributeOverrides(opts, ignore_installed=False)
        requirement_set = command.run(opts, args)
        # Make sure the output of pip and pip-accel are not intermingled.
        sys.stdout.flush()
        if requirement_set is None:
            raise NothingToDoError("""
                pip didn't generate a requirement set, most likely you
                specified an empty requirements file?
            """)
        else:
            return self.transform_pip_requirement_set(requirement_set)


Instruction:
Create a Python 3 function to
transform pip s requirement set into one that pip - accel can work with.

Response:
def transform_pip_requirement_set(self, requirement_set):
        """
        Transform pip's requirement set into one that `pip-accel` can work with.

        :param requirement_set: The :class:`pip.req.RequirementSet` object
                                reported by pip.
        :returns: A list of :class:`pip_accel.req.Requirement` objects.

        This function converts the :class:`pip.req.RequirementSet` object
        reported by pip into a list of :class:`pip_accel.req.Requirement`
        objects.
        """
        filtered_requirements = []
        for requirement in requirement_set.requirements.values():
            # The `satisfied_by' property is set by pip when a requirement is
            # already satisfied (i.e. a version of the package that satisfies
            # the requirement is already installed) and -I, --ignore-installed
            # is not used. We filter out these requirements because pip never
            # unpacks distributions for these requirements, so pip-accel can't
            # do anything useful with such requirements.
            if requirement.satisfied_by:
                continue
            # The `constraint' property marks requirement objects that
            # constrain the acceptable version(s) of another requirement but
            # don't define a requirement themselves, so we filter them out.
            if requirement.constraint:
                continue
            # All other requirements are reported to callers.
            filtered_requirements.append(requirement)
            self.reported_requirements.append(requirement)
        return sorted([Requirement(self.config, r) for r in filtered_requirements],
                      key=lambda r: r.name.lower())


Instruction:
How would you explain what the following Python 3 function does
def install_requirements(self, requirements, **kw):
        install_timer = Timer()
        install_types = []
        if any(not req.is_wheel for req in requirements):
            install_types.append('binary')
        if any(req.is_wheel for req in requirements):
            install_types.append('wheel')
        logger.info("Installing from %s distributions ..", concatenate(install_types))
        # Track installed files by default (unless the caller specifically opted out).
        kw.setdefault('track_installed_files', True)
        num_installed = 0
        for requirement in requirements:
            # When installing setuptools we need to uninstall distribute,
            # otherwise distribute will shadow setuptools and all sorts of
            # strange issues can occur (e.g. upgrading to the latest
            # setuptools to gain wheel support and then having everything
            # blow up because distribute doesn't know about wheels).
            if requirement.name == 'setuptools' and is_installed('distribute'):
                uninstall('distribute')
            if requirement.is_editable:
                logger.debug("Installing %s in editable form using pip.", requirement)
                with TransactionalUpdate(requirement):
                    command = InstallCommand()
                    opts, args = command.parse_args(['--no-deps', '--editable', requirement.source_directory])
                    command.run(opts, args)
            elif requirement.is_wheel:
                logger.info("Installing %s wheel distribution using pip ..", requirement)
                with TransactionalUpdate(requirement):
                    wheel_version = pip_wheel_module.wheel_version(requirement.source_directory)
                    pip_wheel_module.check_compatibility(wheel_version, requirement.name)
                    requirement.pip_requirement.move_wheel_files(requirement.source_directory)
            else:
                logger.info("Installing %s binary distribution using pip-accel ..", requirement)
                with TransactionalUpdate(requirement):
                    binary_distribution = self.bdists.get_binary_dist(requirement)
                    self.bdists.install_binary_dist(binary_distribution, **kw)
            num_installed += 1
        logger.info("Finished installing %s in %s.",
                    pluralize(num_installed, "requirement"),
                    install_timer)
        return num_installed

Response: Manually install a set of requirements from binary or wheel distributions.


Instruction:
Here you have a function in Python 3, explain what it does
def clear_build_directory(self):
        stat = os.stat(self.build_directory)
        shutil.rmtree(self.build_directory)
        os.makedirs(self.build_directory, stat.st_mode)

Response: Clear the build directory where pip unpacks the source distribution archives.


Instruction:
Explain what the following Python 3 code does
def cleanup_temporary_directories(self):
        while self.build_directories:
            shutil.rmtree(self.build_directories.pop())
        for requirement in self.reported_requirements:
            requirement.remove_temporary_source()
        while self.eggs_links:
            symbolic_link = self.eggs_links.pop()
            if os.path.islink(symbolic_link):
                os.unlink(symbolic_link)

Response: Delete the build directories and any temporary directories created by pip.


Instruction:
How would you implement a function in Python 3 that
changes the severity of selected log records.

Response:
def filter(self, record):
        """Change the severity of selected log records."""
        if isinstance(record.msg, basestring):
            message = record.msg.lower()
            if all(kw in message for kw in self.KEYWORDS):
                record.levelname = 'DEBUG'
                record.levelno = logging.DEBUG
        return 1


Instruction:
How would you code a function in Python 3 to
check if a distribution archive exists in the local cache.

Response:
def get(self, filename):
        """
        Check if a distribution archive exists in the local cache.

        :param filename: The filename of the distribution archive (a string).
        :returns: The pathname of a distribution archive on the local file
                  system or :data:`None`.
        """
        pathname = os.path.join(self.config.binary_cache, filename)
        if os.path.isfile(pathname):
            logger.debug("Distribution archive exists in local cache (%s).", pathname)
            return pathname
        else:
            logger.debug("Distribution archive doesn't exist in local cache (%s).", pathname)
            return None


Instruction:
Create a Python 3 function to
store a distribution archive in the local cache.

Response:
def put(self, filename, handle):
        """
        Store a distribution archive in the local cache.

        :param filename: The filename of the distribution archive (a string).
        :param handle: A file-like object that provides access to the
                       distribution archive.
        """
        file_in_cache = os.path.join(self.config.binary_cache, filename)
        logger.debug("Storing distribution archive in local cache: %s", file_in_cache)
        makedirs(os.path.dirname(file_in_cache))
        # Stream the contents of the distribution archive to a temporary file
        # to avoid race conditions (e.g. partial reads) between multiple
        # processes that are using the local cache at the same time.
        with AtomicReplace(file_in_cache) as temporary_file:
            with open(temporary_file, 'wb') as temporary_file_handle:
                shutil.copyfileobj(handle, temporary_file_handle)
        logger.debug("Finished caching distribution archive in local cache.")


Instruction:
Can you tell what is the following Python 3 function doing
def to_python(self, value):
        "Normalize data to a list of strings."
        # Return None if no input was given.
        if not value:
            return []
        return [v.strip() for v in value.splitlines() if v != ""]

Response: Normalize data to a list of strings.


Instruction:
How would you explain what the following Python 3 function does
def validate(self, value):
        "Check if value consists only of valid emails."

        # Use the parent's handling of required fields, etc.
        super(MultiEmailField, self).validate(value)
        try:
            for email in value:
                validate_email(email)
        except ValidationError:
            raise ValidationError(self.message, code=self.code)

Response: Check if value consists only of valid emails.


Instruction:
Explain what the following Python 3 code does
def prep_value(self, value):
        if value in MULTI_EMAIL_FIELD_EMPTY_VALUES:
            return ""
        elif isinstance(value, six.string_types):
            return value
        elif isinstance(value, list):
            return "\n".join(value)
        raise ValidationError('Invalid format.')

Response: Prepare value before effectively render widget


Instruction:
Can you create a Python 3 function that
pauses the current process indefinitely.

Response:
def pause() -> None:
    """
    Pauses the current process indefinitely -- it will require another process to `resume()` it. When this resumption
    happens, the process returns from this function.
    """
    if _logger is not None:
        _log(INFO, "Process", local.name, "pause")
    Process.current().rsim()._gr.switch()


Instruction:
Given the following Python 3 function, write the documentation
def advance(delay: float) -> None:
    if _logger is not None:
        _log(INFO, "Process", local.name, "advance", delay=delay)
    curr = Process.current()
    rsim = curr.rsim
    id_wakeup = rsim()._schedule(delay, curr.switch)  # type: ignore

    try:
        rsim()._gr.switch()                   # type: ignore
    except Interrupt:
        rsim()._cancel(id_wakeup)             # type: ignore
        raise

Response: Pauses the current process for the given delay in simulated time.


Instruction:
Explain what the following Python 3 code does
def happens(intervals: Iterable[float], name: Optional[str] = None) -> Callable:
    def hook(event: Callable):
        def make_happen(*args_event: Any, **kwargs_event: Any) -> None:
            if name is not None:
                local.name = cast(str, name)
            for interval in intervals:
                advance(interval)
                add(event, *args_event, **kwargs_event)
        return make_happen
    return hook

Response: Decorator that returns a function that runs a process at a given set of intervals.


Instruction:
Can you generate the documentation for the following Python 3 function
def tagged(*tags: Tags) -> Callable:
    global GREENSIM_TAG_ATTRIBUTE
    """
    Decorator for adding a label to the process.
    These labels are applied to any child Processes produced by event
    """
    def hook(event: Callable):
        def wrapper(*args, **kwargs):
            event(*args, **kwargs)
        setattr(wrapper, GREENSIM_TAG_ATTRIBUTE, tags)
        return wrapper
    return hook

Response: Decorator for adding a label to the process.


Instruction:
Can you implement a function in Python 3 that
allows the current process to wait for multiple concurrent signals.

Response:
def select(*signals: Signal, **kwargs) -> List[Signal]:
    """
    Allows the current process to wait for multiple concurrent signals. Waits until one of the signals turns on, at
    which point this signal is returned.

    :param timeout:
        If this parameter is not ``None``, it is taken as a delay at the end of which the process times out, and
        stops waiting on the set of :py:class:`Signal`s. In such a situation, a :py:class:`Timeout` exception is raised
        on the process.
    """
    class CleanUp(Interrupt):
        pass

    timeout = kwargs.get("timeout", None)
    if not isinstance(timeout, (float, int, type(None))):
        raise ValueError("The timeout keyword parameter can be either None or a number.")

    def wait_one(signal: Signal, common: Signal) -> None:
        try:
            signal.wait()
            common.turn_on()
        except CleanUp:
            pass

    # We simply sets up multiple sub-processes respectively waiting for one of the signals. Once one of them has fired,
    # the others will all run no-op eventually, so no need for any explicit clean-up.
    common = Signal(name=local.name + "-selector").turn_off()
    if _logger is not None:
        _log(INFO, "select", "select", "select", signals=[sig.name for sig in signals])
    procs = []
    for signal in signals:
        procs.append(add(wait_one, signal, common))

    try:
        common.wait(timeout)
    finally:
        for proc in procs:  # Clean up the support processes.
            proc.interrupt(CleanUp())

    return [signal for signal in signals if signal.is_on]


Instruction:
Create a Python 3 function for
iterating over scheduled events.

Response:
def events(self) -> Iterable[Tuple[Optional[float], Callable, Sequence[Any], Mapping[str, Any]]]:
        """
        Iterates over scheduled events. Each event is a 4-tuple composed of the moment (on the simulated clock) the
        event should execute, the function corresponding to the event, its positional parameters (as a tuple of
        arbitrary length), and its keyword parameters (as a dictionary).
        """
        return (
            (event.timestamp, event.fn, event.args, event.kwargs)
            for event in self._events
            if not event.is_cancelled
        )


Instruction:
Can you tell what is the following Python 3 function doing
def _schedule(self, delay: float, event: Callable, *args: Any, **kwargs: Any) -> int:
        if _logger is not None:
            self._log(
                DEBUG,
                "schedule",
                delay=delay,
                fn=event,
                args=args,
                kwargs=kwargs,
                counter=self._counter,
                __now=self.now()
            )
        delay = float(delay)
        if delay < 0.0:
            raise ValueError("Delay must be positive.")

        # Use counter to strictly order events happening at the same simulated time. This gives a total order on events,
        # working around the heap queue not yielding a stable ordering.
        id_event = self._counter
        heappush(self._events, _Event(self._ts_now + delay, id_event, event, *args, **kwargs))
        self._counter += 1
        return id_event

Response: Schedules a one - time event to be run along the simulation.


Instruction:
How would you code a function in Python 3 to
cancel a previously scheduled event.

Response:
def _cancel(self, id_cancel) -> None:
        """
        Cancels a previously scheduled event. This method is private, and is meant for internal usage by the
        :py:class:`Simulator` and :py:class:`Process` classes, and helper functions of this module.
        """
        if _logger is not None:
            self._log(DEBUG, "cancel", id=id_cancel)
        for event in self._events:
            if event.identifier == id_cancel:
                event.cancel()
                break


Instruction:
Can you generate the documentation for the following Python 3 function
def add(self, fn_process: Callable, *args: Any, **kwargs: Any) -> 'Process':
        return self.add_in(0.0, fn_process, *args, **kwargs)

Response: Adds a process to the simulation.


Instruction:
Can you write a function in Python 3 where it
adds a process to the simulation which is made to start after the given delay in simulated time.

Response:
def add_in(self, delay: float, fn_process: Callable, *args: Any, **kwargs: Any) -> 'Process':
        """
        Adds a process to the simulation, which is made to start after the given delay in simulated time.

        See method add() for more details.
        """
        process = Process(self, fn_process, self._gr)
        if _logger is not None:
            self._log(INFO, "add", __now=self.now(), fn=fn_process, args=args, kwargs=kwargs)
        self._schedule(delay, process.switch, *args, **kwargs)
        return process


Instruction:
Write a Python 3 function that can
add a process to the simulation which is made to start at the given time.

Response:
def add_at(self, moment: float, fn_process: Callable, *args: Any, **kwargs: Any) -> 'Process':
        """
        Adds a process to the simulation, which is made to start at the given exact time on the simulated clock. Note
        that times in the past when compared to the current moment on the simulated clock are forbidden.

        See method add() for more details.
        """
        delay = moment - self.now()
        if delay < 0.0:
            raise ValueError(
                f"The given moment to start the process ({moment:f}) is in the past (now is {self.now():f})."
            )
        return self.add_in(delay, fn_process, *args, **kwargs)


Instruction:
Write a Python 3 script for
running the simulation until a stopping condition is met.

Response:
def run(self, duration: float = inf) -> None:
        """
        Runs the simulation until a stopping condition is met (no more events, or an event invokes method stop()), or
        until the simulated clock hits the given duration.
        """
        if _logger is not None:
            self._log(INFO, "run", __now=self.now(), duration=duration)
        counter_stop_event = None
        if duration != inf:
            counter_stop_event = self._counter
            self._schedule(duration, self.stop)

        self._is_running = True
        while self.is_running and len(self._events) > 0:
            event = heappop(self._events)
            self._ts_now = event.timestamp or self._ts_now
            event.execute(self)

        if len(self._events) == 0:
            if _logger is not None:
                self._log(DEBUG, "out-of-events", __now=self.now())
        self.stop()

        if counter_stop_event is not None:
            # Change the planned stop to a no-op. We would rather eliminate it, but this would force a re-sort of the
            # event queue.
            for (i, event) in enumerate(self._events):
                if event.identifier == counter_stop_event:
                    if _logger is not None:
                        self._log(DEBUG, "cancel-stop", counter=counter_stop_event)
                    event.cancel()
                    break


Instruction:
Can you generate a brief explanation for the following Python 3 code
def step(self) -> None:
        event = heappop(self._events)
        self._ts_now = event.timestamp or self._ts_now
        event.execute(self)

Response: Runs a single event of the simulation.


Instruction:
How would you code a function in Python 3 to
stop the running simulation once the current event is done executing.

Response:
def stop(self) -> None:
        """
        Stops the running simulation once the current event is done executing.
        """
        if self.is_running:
            if _logger is not None:
                self._log(INFO, "stop", __now=self.now())
            self._is_running = False


Instruction:
Write a Python 3 script for
clearing the internal state of the simulation and resets the simulated clock to 0. 0.

Response:
def _clear(self) -> None:
        """
        Resets the internal state of the simulator, and sets the simulated clock back to 0.0. This discards all
        outstanding events and tears down hanging process instances.
        """
        for _, event, _, _ in self.events():
            if hasattr(event, "__self__") and isinstance(event.__self__, Process):  # type: ignore
                event.__self__.throw()                                              # type: ignore
        self._events.clear()
        self._ts_now = 0.0


Instruction:
Write a Python 3 script to
wrap around the _body method to catch Interrupt and finish the process.

Response:
def _run(self, *args: Any, **kwargs: Any) -> None:
        """
        Wraps around the process body (the function that implements a process within the simulation) so as to catch the
        eventual Interrupt that may terminate the process.
        """
        try:
            self._body(*args, **kwargs)
            if _logger is not None:
                _log(INFO, "Process", self.local.name, "die-finish")
        except Interrupt:
            if _logger is not None:
                _log(INFO, "Process", self.local.name, "die-interrupt")


Instruction:
Can you implement a function in Python 3 that
binds and call the constructor of a type directly and the TaggedObject s __init__ method.

Response:
def _bind_and_call_constructor(self, t: type, *args) -> None:
        """
        Accesses the __init__ method of a type directly and calls it with *args

        This allows the constructors of both superclasses to be called, as described in get_binding.md

        This could be done using two calls to super() with a hack based on how Python searches __mro__:

        ```
        super().__init__(run, parent) # calls greenlet.greenlet.__init__
        super(greenlet.greenlet, self).__init__() # calls TaggedObject.__init__
        ```

        Python will always find greenlet.greenlet first since it is specified first, but will ignore it if it is
        the first argument to super, which is meant to indicate the subclass and thus is not meant to be called on

        See: https://docs.python.org/3.7/library/functions.html#super

        This is indirect, confusing, and not in following with the purpose of super(), so the direct method was used
        """
        t.__init__.__get__(self)(*args)


Instruction:
Write a Python 3 script to
return the current process instance.

Response:
def current() -> 'Process':
        """
        Returns the instance of the process that is executing at the current moment.
        """
        curr = greenlet.getcurrent()
        if not isinstance(curr, Process):
            raise TypeError("Current greenlet does not correspond to a Process instance.")
        return cast(Process, greenlet.getcurrent())


Instruction:
Can you tell what is the following Python 3 function doing
def resume(self) -> None:
        if _logger is not None:
            _log(INFO, "Process", self.local.name, "resume")
        self.rsim()._schedule(0.0, self.switch)

Response: Resumes a process that has been previously paused by invoking function resume.


Instruction:
Explain what the following Python 3 code does
def interrupt(self, inter: Optional[Interrupt] = None) -> None:
        if inter is None:
            inter = Interrupt()
        if _logger is not None:
            _log(INFO, "Process", self.local.name, "interrupt", type=type(inter).__name__)
        self.rsim()._schedule(0.0, self.throw, inter)

Response: Interrupts a process that has been previously paused or made to advance or raise an Interrupt exception on it.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def join(self, timeout: Optional[float] = None):
        class CancelBalk(Interrupt):
            pass

        self._counter += 1
        if _logger is not None:
            self._log(INFO, "join")
        heappush(self._waiting, (self._get_order_token(self._counter), Process.current()))

        proc_balk = None
        if timeout is not None:
            def balk(proc):
                nonlocal proc_balk
                try:
                    advance(cast(float, timeout))
                    proc.interrupt(Timeout())
                except CancelBalk:
                    pass
                finally:
                    proc_balk = None

            # The balking process is started here.
            proc_balk = add(balk, Process.current())

        try:
            pause()
        except Interrupt:
            current = Process.current()
            for index in reversed([i for i, (_, proc) in enumerate(self._waiting) if proc is current]):
                del self._waiting[index]
            heapify(self._waiting)
            raise
        finally:
            # Three situations can prompt a process to exit a queue:
            #
            # 1. The process is pop()ped out of the queue by a peer.
            # 2. The process balk()s out after a timeout.
            # 3. The process leaves the queue because of a distinct interrupt (besides CancelBalk).
            #
            # In cases 1 and 3, the balking process has never exited and is still in the advance() call. In both these
            # cases, the balking process should itself be interrupted, otherwise it may prompt the balking of a future
            # queue traversal. However, if we exit the queue because of case no. 2, the balking process is finished.
            # Interrupting it would do no harm (it has been tested by accident), but we mean to be deliberate about when
            # this interruption is necessary. So we perform the interrupt of the balking process only in cases 1 and 3;
            # in case 2, the balk() function exits, thereby clearing the reference we have here to it. Do remark that
            # whenever a timeout is not set, proc_balk remains None all the way, reducing the situation to case 1.
            if proc_balk is not None:
                proc_balk.interrupt(CancelBalk())

Response: This method is used to join the process queue.


Instruction:
Can you tell what is the following Python 3 function doing
def pop(self):
        if not self.is_empty():
            _, process = heappop(self._waiting)
            if _logger is not None:
                self._log(INFO, "pop", process=process.local.name)
            process.resume()

Response: Removes the top process from the queue and resumes its execution.


Instruction:
How would you implement a function in Python 3 that
turns on the signal.

Response:
def turn_on(self) -> "Signal":
        """
        Turns on the signal. If processes are waiting, they are all resumed. This may be invoked from any code.

        Remark that while processes are simultaneously resumed in simulated time, they are effectively resumed in the
        sequence corresponding to the queue discipline. Therefore, if one of the resumed processes turns the signal back
        off, remaining resumed processes join back the queue. If the queue discipline is not monotonic (for instance,
        if it bears a random component), then this toggling of the signal may reorder the processes.
        """
        if _logger is not None:
            self._log(INFO, "turn-on")
        self._is_on = True
        while not self._queue.is_empty():
            self._queue.pop()
        return self


Instruction:
Write a Python 3 function that can
turn off the signal.

Response:
def turn_off(self) -> "Signal":
        """
        Turns off the signal. This may be invoked from any code.
        """
        if _logger is not None:
            self._log(INFO, "turn-off")
        self._is_on = False
        return self


Instruction:
Can you tell what is the following Python 3 function doing
def wait(self, timeout: Optional[float] = None) -> None:
        if _logger is not None:
            self._log(INFO, "wait")
        while not self.is_on:
            self._queue.join(timeout)

Response: Waits for the current process to exit.


Instruction:
How would you explain what the following Python 3 function does
def take(self, num_instances: int = 1, timeout: Optional[float] = None) -> None:

        if num_instances < 1:
            raise ValueError(f"Process must request at least 1 instance; here requested {num_instances}.")
        if num_instances > self.num_instances_total:
            raise ValueError(
                f"Process must request at most {self.num_instances_total} instances; here requested {num_instances}."
            )
        if _logger is not None:
            self._log(INFO, "take", num_instances=num_instances, free=self.num_instances_free)
        proc = Process.current()
        if self._num_instances_free < num_instances:
            proc.local.__num_instances_required = num_instances
            try:
                self._waiting.join(timeout)
            finally:
                del proc.local.__num_instances_required
        self._num_instances_free -= num_instances
        if _logger is not None and proc in self._usage:
            self._log(WARNING, "take-again", already=self._usage[proc], more=num_instances)
        self._usage.setdefault(proc, 0)
        self._usage[proc] += num_instances

Response: Take the specified number of resource instances from the queue.


Instruction:
How would you implement a function in Python 3 that
releases the specified number of instances.

Response:
def release(self, num_instances: int = 1) -> None:
        """
        The current process releases instances it has previously taken. It may thus release less than it has taken.
        These released instances become free. If the total number of free instances then satisfy the request of the top
        process of the waiting queue, it is popped off the queue and resumed.
        """
        proc = Process.current()
        error_format = "Process %s holds %s instances, but requests to release more (%s)"
        if self._usage.get(proc, 0) > 0:
            if num_instances > self._usage[proc]:
                raise ValueError(
                    error_format % (proc.local.name, self._usage[proc], num_instances)
                )
            self._usage[proc] -= num_instances
            self._num_instances_free += num_instances
            if _logger is not None:
                self._log(
                    INFO,
                    "release",
                    num_instances=num_instances,
                    keeping=self._usage[proc],
                    free=self.num_instances_free
                )
            if self._usage[proc] <= 0:
                del self._usage[proc]
            if not self._waiting.is_empty():
                num_instances_next = cast(int, self._waiting.peek().local.__num_instances_required)
                if num_instances_next <= self.num_instances_free:
                    self._waiting.pop()
                elif _logger is not None:
                    self._log(DEBUG, "release-nopop", next_requires=num_instances_next, free=self.num_instances_free)
            elif _logger is not None:
                self._log(DEBUG, "release-queueempty")
        else:
            raise RuntimeError(
                f"Process {proc.local.name} tries to release {num_instances} instances, but is holding none.)"
            )


Instruction:
Can you generate the documentation for the following Python 3 function
def using(self, num_instances: int = 1, timeout: Optional[float] = None):
        self.take(num_instances, timeout)
        yield self
        self.release(num_instances)

Response: Context manager around resource reservation.


Instruction:
Write a Python 3 script to
progress capture that writes updated metrics to an interactive terminal.

Response:
def capture_print(file_dest_maybe: Optional[IO] = None):
    """Progress capture that writes updated metrics to an interactive terminal."""
    file_dest: IO = file_dest_maybe or sys.stderr

    def _print_progress(progress_min: float, rt_remaining: float, _mc: MeasureComparison) -> None:
        nonlocal file_dest
        percent_progress = progress_min * 100.0
        time_remaining, unit = _display_time(rt_remaining)
        print(
            f"Progress: {percent_progress:.1f}% -- Time remaining: {time_remaining} {unit}          ",
            end="\r",
            file=file_dest
        )

    return _print_progress


Instruction:
Create a Python 3 function for
tracking the progress of a given measure against a target.

Response:
def track_progress(
    measure: MeasureProgress,
    target: MetricProgress,
    interval_check: float,
    capture_maybe: Optional[CaptureProgress] = None
) -> None:
    """
    Tracks progress against a certain end condition of the simulation (for instance, a certain duration on the simulated
    clock), reporting this progress as the simulation chugs along. Stops the simulation once the target has been
    reached. By default, the progress is reported as printout on standard output, in a manner that works best for
    digital terminals.
    """

    def measure_to_target() -> MeasureComparison:
        return list(zip(measure(), target))

    def is_finished(progress: MeasureComparison) -> bool:
        return all(p >= t for p, t in progress)

    capture = capture_maybe or capture_print()
    rt_started = now_real()
    while True:
        advance(interval_check)

        rt_elapsed = now_real() - rt_started
        progress = measure_to_target()
        ratio_progress_min = min(m / t for m, t in progress)
        if ratio_progress_min == 0.0:
            rt_total_projected = inf
        else:
            rt_total_projected = rt_elapsed / ratio_progress_min
        capture(ratio_progress_min, rt_total_projected - rt_elapsed, progress)

        if is_finished(progress):
            stop()
            break


Instruction:
Explain what the following Python 3 code does
def calcTm(seq, mv_conc=50, dv_conc=0, dntp_conc=0.8, dna_conc=50,
           max_nn_length=60, tm_method='santalucia',
           salt_corrections_method='santalucia'):
    ''' Return the tm of `seq` as a float.
    '''
    tm_meth = _tm_methods.get(tm_method)
    if tm_meth is None:
        raise ValueError('{} is not a valid tm calculation method'.format(
                         tm_method))
    salt_meth = _salt_corrections_methods.get(salt_corrections_method)
    if salt_meth is None:
        raise ValueError('{} is not a valid salt correction method'.format(
                         salt_corrections_method))
    # For whatever reason mv_conc and dna_conc have to be ints
    args = [pjoin(PRIMER3_HOME, 'oligotm'),
            '-mv',  str(mv_conc),
            '-dv',  str(dv_conc),
            '-n',   str(dntp_conc),
            '-d',   str(dna_conc),
            '-tp',  str(tm_meth),
            '-sc',  str(salt_meth),
            seq]
    tm = subprocess.check_output(args, stderr=DEV_NULL,
                                 env=os.environ)
    return float(tm)

Response: Calculate the tm of a sequence.


Instruction:
Here you have a function in Python 3, explain what it does
def calcThermo(seq1, seq2, calc_type='ANY', mv_conc=50, dv_conc=0,
                 dntp_conc=0.8, dna_conc=50, temp_c=37, max_loop=30,
                 temp_only=False):
    """ Main subprocess wrapper for calls to the ntthal executable.

    Returns a named tuple with tm, ds, dh, and dg values or None if no
    structure / complex could be computed.
    """
    args = [pjoin(PRIMER3_HOME, 'ntthal'),
            '-a',       str(calc_type),
            '-mv',      str(mv_conc),
            '-dv',      str(dv_conc),
            '-n',       str(dntp_conc),
            '-d',       str(dna_conc),
            '-t',       str(temp_c),
            '-maxloop', str(max_loop),
            '-path',    THERMO_PATH,
            '-s1',      seq1,
            '-s2',      seq2]
    if temp_only:
        args += ['-r']
    out = subprocess.check_output(args, stderr=DEV_NULL,
                                  env=os.environ)
    return _parse_ntthal(out)

Response: This function calls the ntthal executable and returns the output of the ntthal executable.


Instruction:
Can you generate the documentation for the following Python 3 function
def calcHairpin(seq, mv_conc=50, dv_conc=0, dntp_conc=0.8, dna_conc=50,
                 temp_c=37, max_loop=30, temp_only=False):
    ''' Return a namedtuple of the dS, dH, dG, and Tm of any hairpin struct
    present.
    '''
    return calcThermo(seq, seq, 'HAIRPIN', mv_conc, dv_conc, dntp_conc,
                      dna_conc, temp_c, max_loop, temp_only)

Response: Calculates the thermo of the hairpin structure.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def calcHeterodimer(seq1, seq2, mv_conc=50, dv_conc=0, dntp_conc=0.8,
                     dna_conc=50, temp_c=37, max_loop=30, temp_only=False):
    ''' Return a tuple of the dS, dH, dG, and Tm of any predicted heterodimer.
    '''
    return calcThermo(seq1, seq2, 'ANY', mv_conc, dv_conc, dntp_conc,
                      dna_conc, temp_c, max_loop, temp_only)

Response: Calculate the heterodimer of the two sequences.


Instruction:
Write a Python 3 function for
assessing the hairpin and homodimer characteristics of a sequence of thermodynamic characteristics.

Response:
def assessOligo(seq):
    '''
    Return the thermodynamic characteristics of hairpin/homodimer structures.

    Returns a tuple of namedtuples (hairpin data, homodimer data) in which each
    individual tuple is structured (dS, dH, dG, Tm).

    '''
    hairpin_out = calcHairpin(seq)
    homodimer_out = calcHomodimer(seq)
    return (hairpin_out, homodimer_out)


Instruction:
Can you generate the documentation for the following Python 3 function
def designPrimers(p3_args, input_log=None, output_log=None, err_log=None):
    ''' Return the raw primer3_core output for the provided primer3 args.

    Returns an ordered dict of the boulderIO-format primer3 output file
    '''
    sp = subprocess.Popen([pjoin(PRIMER3_HOME, 'primer3_core')],
                          stdout=subprocess.PIPE, stdin=subprocess.PIPE,
                          stderr=subprocess.STDOUT)
    p3_args.setdefault('PRIMER_THERMODYNAMIC_PARAMETERS_PATH',
                       pjoin(PRIMER3_HOME, 'primer3_config/'))
    in_str = _formatBoulderIO(p3_args)
    if input_log:
        input_log.write(in_str)
        input_log.flush()
    out_str, err_str = sp.communicate(input=in_str)
    if output_log:
        output_log.write(out_str)
        output_log.flush()
    if err_log and err_str is not None:
        err_log.write(err_str)
        err_log.flush()
    return _parseBoulderIO(out_str)

Response: Return the raw primer3_core output for the provided primer3 args.


Instruction:
Create a Python 3 function for
adding the executable bit to the file at filepath fp

Response:
def makeExecutable(fp):
    ''' Adds the executable bit to the file at filepath `fp`
    '''
    mode = ((os.stat(fp).st_mode) | 0o555) & 0o7777
    setup_log.info("Adding executable bit to %s (mode is now %o)", fp, mode)
    os.chmod(fp, mode)