Instruction:
Explain what the following Python 3 code does
def gen_textfiles_from_filenames(
        filenames: Iterable[str]) -> Generator[TextIO, None, None]:
    """
    Generates file-like objects from a list of filenames.

    Args:
        filenames: iterable of filenames

    Yields:
        each file as a :class:`TextIO` object

    """
    for filename in filenames:
        with open(filename) as f:
            yield f

Response: Generates file - like objects from a list of filenames.


Instruction:
Write a Python 3 script to
generate lines from file - like objects.

Response:
def gen_lines_from_textfiles(
        files: Iterable[TextIO]) -> Generator[str, None, None]:
    """
    Generates lines from file-like objects.

    Args:
        files: iterable of :class:`TextIO` objects

    Yields:
        each line of all the files

    """
    for file in files:
        for line in file:
            yield line


Instruction:
How would you implement a function in Python 3 that
returns an iterable of strings that are lower cased.

Response:
def gen_lower(x: Iterable[str]) -> Generator[str, None, None]:
    """
    Args:
        x: iterable of strings

    Yields:
        each string in lower case
    """
    for string in x:
        yield string.lower()


Instruction:
Can you write a function in Python 3 where it
generates lines from binary files.

Response:
def gen_lines_from_binary_files(
        files: Iterable[BinaryIO],
        encoding: str = UTF8) -> Generator[str, None, None]:
    """
    Generates lines from binary files.
    Strips out newlines.

    Args:
        files: iterable of :class:`BinaryIO` file-like objects
        encoding: encoding to use

    Yields:
        each line of all the files

    """
    for file in files:
        for byteline in file:
            line = byteline.decode(encoding).strip()
            yield line


Instruction:
Write a Python 3 script for
splitting lines with splitter and yields a specified part by index.

Response:
def gen_part_from_line(lines: Iterable[str],
                       part_index: int,
                       splitter: str = None) -> Generator[str, None, None]:
    """
    Splits lines with ``splitter`` and yields a specified part by index.

    Args:
        lines: iterable of strings
        part_index: index of part to yield
        splitter: string to split the lines on

    Yields:
        the specified part for each line

    """
    for line in lines:
        parts = line.split(splitter)
        yield parts[part_index]


Instruction:
Can you generate a brief explanation for the following Python 3 code
def gen_rows_from_csv_binfiles(
        csv_files: Iterable[BinaryIO],
        encoding: str = UTF8,
        skip_header: bool = False,
        **csv_reader_kwargs) -> Generator[Iterable[str], None, None]:
    """
    Iterate through binary file-like objects that are CSV files in a specified
    encoding. Yield each row.

    Args:
        csv_files: iterable of :class:`BinaryIO` objects
        encoding: encoding to use
        skip_header: skip the header (first) row of each file?
        csv_reader_kwargs: arguments to pass to :func:`csv.reader`

    Yields:
        rows from the files

    """
    dialect = csv_reader_kwargs.pop('dialect', None)
    for csv_file_bin in csv_files:
        # noinspection PyTypeChecker
        csv_file = io.TextIOWrapper(csv_file_bin, encoding=encoding)
        thisfile_dialect = dialect
        if thisfile_dialect is None:
            thisfile_dialect = csv.Sniffer().sniff(csv_file.read(1024))
            csv_file.seek(0)
        reader = csv.reader(csv_file, dialect=thisfile_dialect,
                            **csv_reader_kwargs)
        first = True
        for row in reader:
            if first:
                first = False
                if skip_header:
                    continue
            yield row

Response: Generator that yields each row of the CSV file - like object in a specified encoding.


Instruction:
Write a Python 3 script to
rewrite a file from srcfilename to destfilename HTML - escaping it IVA in the process.

Response:
def webify_file(srcfilename: str, destfilename: str) -> None:
    """
    Rewrites a file from ``srcfilename`` to ``destfilename``, HTML-escaping it
    in the process.
    """
    with open(srcfilename) as infile, open(destfilename, 'w') as ofile:
        for line_ in infile:
            ofile.write(escape(line_))


Instruction:
How would you explain what the following Python 3 function does
def remove_gzip_timestamp(filename: str,
                          gunzip_executable: str = "gunzip",
                          gzip_executable: str = "gzip",
                          gzip_args: List[str] = None) -> None:
    """
    Uses external ``gunzip``/``gzip`` tools to remove a ``gzip`` timestamp.
    Necessary for Lintian.
    """
    gzip_args = gzip_args or [
        "-9",  # maximum compression (or Lintian moans)
        "-n",
    ]
    # gzip/gunzip operate on SINGLE files
    with tempfile.TemporaryDirectory() as dir_:
        basezipfilename = os.path.basename(filename)
        newzip = os.path.join(dir_, basezipfilename)
        with open(newzip, 'wb') as z:
            log.info(
                "Removing gzip timestamp: "
                "{} -> gunzip -c -> gzip -n -> {}",
                basezipfilename, newzip)
            p1 = subprocess.Popen([gunzip_executable, "-c", filename],
                                  stdout=subprocess.PIPE)
            p2 = subprocess.Popen([gzip_executable] + gzip_args,
                                  stdin=p1.stdout, stdout=z)
            p2.communicate()
        shutil.copyfile(newzip, filename)

Response: Removes a gzip timestamp from a single file.


Instruction:
Can you tell what is the following Python 3 function doing
def replace_in_file(filename: str, text_from: str, text_to: str) -> None:
    log.info("Amending {}: {} -> {}",
             filename, repr(text_from), repr(text_to))
    with open(filename) as infile:
        contents = infile.read()
    contents = contents.replace(text_from, text_to)
    with open(filename, 'w') as outfile:
        outfile.write(contents)

Response: Replaces text in a file.


Instruction:
Implement a function in Python 3 to
replace multiple from and to strings pairs within a single file.

Response:
def replace_multiple_in_file(filename: str,
                             replacements: List[Tuple[str, str]]) -> None:
    """
    Replaces multiple from/to string pairs within a single file.

    Args:
        filename: filename to process (modifying it in place)
        replacements: list of ``(from_text, to_text)`` tuples
    """
    with open(filename) as infile:
        contents = infile.read()
    for text_from, text_to in replacements:
        log.info("Amending {}: {} -> {}",
                 filename, repr(text_from), repr(text_to))
        contents = contents.replace(text_from, text_to)
    with open(filename, 'w') as outfile:
        outfile.write(contents)


Instruction:
Write a Python 3 function for
converting a file from UNIX to Windows line endings or the alphabetical order.

Response:
def convert_line_endings(filename: str, to_unix: bool = False,
                         to_windows: bool = False) -> None:
    """
    Converts a file (in place) from UNIX to Windows line endings, or the
    reverse.

    Args:
        filename: filename to modify (in place)
        to_unix: convert Windows (CR LF) to UNIX (LF)
        to_windows: convert UNIX (LF) to Windows (CR LF)
    """
    assert to_unix != to_windows
    with open(filename, "rb") as f:
        contents = f.read()
    windows_eol = b"\r\n"  # CR LF
    unix_eol = b"\n"  # LF
    if to_unix:
        log.info("Converting from Windows to UNIX line endings: {!r}",
                 filename)
        src = windows_eol
        dst = unix_eol
    else:  # to_windows
        log.info("Converting from UNIX to Windows line endings: {!r}",
                 filename)
        src = unix_eol
        dst = windows_eol
        if windows_eol in contents:
            log.info("... already contains at least one Windows line ending; "
                     "probably converted before; skipping")
            return
    contents = contents.replace(src, dst)
    with open(filename, "wb") as f:
        f.write(contents)


Instruction:
How would you explain what the following Python 3 function does
def is_line_in_file(filename: str, line: str) -> bool:
    assert "\n" not in line
    with open(filename, "r") as file:
        for fileline in file:
            if fileline == line:
                return True
        return False

Response: Detects whether a line is present within a file.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def add_line_if_absent(filename: str, line: str) -> None:
    assert "\n" not in line
    if not is_line_in_file(filename, line):
        log.info("Appending line {!r} to file {!r}", line, filename)
        with open(filename, "a") as file:
            file.writelines([line])

Response: Adds a line to the file if it s not already in the file.


Instruction:
Can you write a function in Python 3 where it
checks if the get query returned a result and return a boolean

Response:
def is_get_query_with_results(results):
        """
        :param results: the response from Elasticsearch
        :return: true if the get query returned a result, false otherwise
        """
        return results and EsConst.FOUND in results and results[EsConst.FOUND] and EsConst.FIELDS in results


Instruction:
Can you tell what is the following Python 3 function doing
def validate_scan_result(results):
        if results[EsConst.SHARDS][EsConst.FAILED] and results[EsConst.SHARDS][EsConst.FAILED] > 0:
            raise ScanError(
                'Scroll request has failed on %d shards out of %d.' %
                (results[EsConst.SHARDS][EsConst.FAILED], results[EsConst.SHARDS][EsConst.TOTAL])
            )

Response: Check if there s a failed shard in the scan query and if so raise an exception.


Instruction:
Can you generate the documentation for the following Python 3 function
def to_key_val_list(value, sort=False, insensitive=False):
    if value is None:
        return None

    if isinstance(value, (str, bytes, bool, int)):
        raise ValueError('cannot encode objects that are not 2-tuples')

    if isinstance(value, collections.Mapping):
        value = value.items()

    if sort and not insensitive:
        values = sorted(value)
    elif sort:
        values = sorted(value, key=lambda t: t[0].lower())
    else:
        values = value
    return list(values)

Response:
Takes an object and test to see if it can be represented as a
    dictionary. If it can be return a list of tuples. If it can be return a list of tuples.


Instruction:
How would you code a function in Python 3 to
convert a dictionary of values into a key - value dictionary.

Response:
def to_key_val_dict(values):
    """
    Take an object and test to see if it can be represented as a
    dictionary. If it can be, return a list of tuples, e.g.,
    ::
        >>> to_key_val_dict([('key', 'val')])
        {'key': 'val'}
        >>> to_key_val_dict({'key': 'val'})
        {'key': 'val'}
        >>> to_key_val_dict('string')
        ValueError: dictionary update sequence element.
    """
    if values is None:
        return {}

    if isinstance(values, (str, bytes, bool, int)):
        raise ValueError('cannot encode objects that are not 2-tuples')

    if isinstance(values, collections.Mapping):
        values = values.items()

    dict_to_return = dict()
    for k, v in values:
        if k in dict_to_return and isinstance(dict_to_return[k], list) and isinstance(v, list):
            dict_to_return[k].extend(v)
        elif k in dict_to_return and isinstance(dict_to_return[k], list):
            dict_to_return[k].append(v)
        elif k in dict_to_return:
            dict_to_return[k] = [dict_to_return[k], v]
        else:
            dict_to_return[k] = v

    return dict_to_return


Instruction:
Can you generate the documentation for the following Python 3 function
def valid_choice(strvalue: str, choices: Iterable[Tuple[str, str]]) -> bool:
    return strvalue in [str(x[0]) for x in choices]

Response: Checks that value is one of the valid option in choices


Instruction:
Can you generate the documentation for the following Python 3 function
def choice_explanation(value: str, choices: Iterable[Tuple[str, str]]) -> str:
    for k, v in choices:
        if k == value:
            return v
    return ''

Response: Returns the explanation associated with a Django choice tuple - list.


Instruction:
Create a Python 3 function for
running a command and captures its output to one or more TEED files.

Response:
def teed_call(cmd_args,
              stdout_targets: List[TextIO] = None,
              stderr_targets: List[TextIO] = None,
              encoding: str = sys.getdefaultencoding(),
              **kwargs):
    """
    Runs a command and captures its output via :func:`tee` to one or more
    destinations. The output is always captured (otherwise we would lose
    control of the output and ability to ``tee`` it); if no destination is
    specified, we add a null handler.

    We insist on ``TextIO`` output files to match ``sys.stdout`` (etc.).

    A variation on:
    https://stackoverflow.com/questions/4984428/python-subprocess-get-childrens-output-to-file-and-terminal

    Args:
        cmd_args: arguments for the command to run
        stdout_targets: file-like objects to write ``stdout`` to
        stderr_targets: file-like objects to write ``stderr`` to
        encoding: encoding to apply to ``stdout`` and ``stderr``
        kwargs: additional arguments for :class:`subprocess.Popen`

    """  # noqa
    # Make a copy so we can append without damaging the original:
    stdout_targets = stdout_targets.copy() if stdout_targets else []  # type: List[TextIO]  # noqa
    stderr_targets = stderr_targets.copy() if stderr_targets else []  # type: List[TextIO]  # noqa
    p = Popen(cmd_args, stdout=PIPE, stderr=PIPE, **kwargs)
    threads = []  # type: List[Thread]
    with open(os.devnull, "w") as null:  # type: TextIO
        if not stdout_targets:
            stdout_targets.append(null)
        if not stderr_targets:
            stderr_targets.append(null)
        # Now, by default, because we're not using "universal_newlines", both
        # p.stdout and p.stderr are binary.
        stdout_txt = TextIOWrapper(p.stdout, encoding=encoding)  # type: TextIO  # noqa
        stderr_txt = TextIOWrapper(p.stderr, encoding=encoding)  # type: TextIO  # noqa
        threads.append(tee(stdout_txt, *stdout_targets))
        threads.append(tee(stderr_txt, *stderr_targets))
        for t in threads:
            t.join()  # wait for IO completion
        return p.wait()


Instruction:
Write a Python 3 function for
writing a message to the underlying stream.

Response:
def write(self, message: str) -> None:
        """
        To act as a file.
        """
        self.underlying_stream.write(message)
        self.file.write(message)


Instruction:
How would you explain what the following Python 3 function does
def flush(self) -> None:
        self.underlying_stream.flush()
        self.file.flush()
        os.fsync(self.file.fileno())

Response: Flushes the underlying stream and file.


Instruction:
Create a Python 3 function to
close the file and the underlying stream.

Response:
def close(self) -> None:
        """
        To act as a file.
        """
        if self.underlying_stream:
            if self.using_stdout:
                sys.stdout = self.underlying_stream
            else:
                sys.stderr = self.underlying_stream
            self.underlying_stream = None
        if self.file:
            # Do NOT close the file; we don't own it.
            self.file = None
            log.debug("Finished copying {} to {}",
                      self.output_description, self.filename)


Instruction:
How would you code a function in Python 3 to
provide a bootstrap resampling of an array.

Response:
def bootstrap(array):
    """
    Provides a bootstrap resampling of an array. Provides another
    statistical method to estimate the variance of a dataset.

    For a `PCA` object in this library, it should be applied to
    `Orientation.array` method.
    """
    reg_func = lambda a: N.linalg.svd(a,full_matrices=False)[2][2]
    beta_boots = bootstrap(array, func=reg_func)
    return yhat, yhat_boots


Instruction:
Write a Python 3 function for
transforming text into its ANSI SQL - quoted version e. g. in Python 3. 6.

Response:
def sql_string_literal(text: str) -> str:
    """
    Transforms text into its ANSI SQL-quoted version, e.g. (in Python ``repr()``
    format):

    .. code-block:: none

        "some string"   -> "'some string'"
        "Jack's dog"    -> "'Jack''s dog'"
    """
    # ANSI SQL: http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt
    # <character string literal>
    return SQUOTE + text.replace(SQUOTE, DOUBLE_SQUOTE) + SQUOTE


Instruction:
Explain what the following Python 3 code does
def sql_datetime_literal(dt: DateTimeLikeType,
                         subsecond: bool = False) -> str:
    """
    Transforms a Python object that is of duck type ``datetime.datetime`` into
    an ANSI SQL literal string, like ``'2000-12-31 23:59:59'``, or if
    ``subsecond=True``, into the (non-ANSI) format
    ``'2000-12-31 23:59:59.123456'`` or similar.
    """
    # ANSI SQL: http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt
    # <timestamp string>
    # ... the subsecond part is non-ANSI
    fmt = "'%Y-%m-%d %H:%M:%S{}'".format(".%f" if subsecond else "")
    return dt.strftime(fmt)

Response: Transforms a Python object that is of duck type datetime. datetime into an ANSI SQL literal string like 2000 - 12 - 31 23 - 59 - 59.123456.


Instruction:
Can you write a function in Python 3 where it
transforms a single - line string into an ANSI SQL comment.

Response:
def sql_comment(comment: str) -> str:
    """
    Transforms a single- or multi-line string into an ANSI SQL comment,
    prefixed by ``--``.
    """
    """Using -- as a comment marker is ANSI SQL."""
    if not comment:
        return ""
    return "\n".join("-- {}".format(x) for x in comment.splitlines())


Instruction:
Create a Python 3 function for
removing double quotes from a SQL string.

Response:
def sql_dequote_string(s: str) -> str:
    """
    Reverses :func:`sql_quote_string`.
    """
    if len(s) < 2 or s[0] != SQUOTE or s[-1] != SQUOTE:
        raise ValueError("Not an SQL string literal")
    s = s[1:-1]  # strip off the surrounding quotes
    return s.replace(DOUBLE_SQUOTE, SQUOTE)


Instruction:
Explain what the following Python 3 code does
def gen_items_from_sql_csv(s: str) -> Generator[str, None, None]:
    # csv.reader will not both process the quotes and return the quotes;
    # we need them to distinguish e.g. NULL from 'NULL'.
    # log.warning('gen_items_from_sql_csv: s = {0!r}', s)
    if not s:
        return
    n = len(s)
    startpos = 0
    pos = 0
    in_quotes = False
    while pos < n:
        if not in_quotes:
            if s[pos] == COMMA:
                # end of chunk
                chunk = s[startpos:pos]  # does not include s[pos]
                result = chunk.strip()
                # log.warning('yielding: {0!r}', result)
                yield result
                startpos = pos + 1
            elif s[pos] == SQUOTE:
                # start of quote
                in_quotes = True
        else:
            if pos < n - 1 and s[pos] == SQUOTE and s[pos + 1] == SQUOTE:
                # double quote, '', is an escaped quote, not end of quote
                pos += 1  # skip one more than we otherwise would
            elif s[pos] == SQUOTE:
                # end of quote
                in_quotes = False
        pos += 1
    # Last chunk
    result = s[startpos:].strip()
    # log.warning('yielding last: {0!r}', result)
    yield result

Response: Yields the items from a SQL string.


Instruction:
Make a summary of the following Python 3 code
def get_case_insensitive_dict_key(d: Dict, k: str) -> Optional[str]:
    for key in d.keys():
        if k.lower() == key.lower():
            return key
    return None

Response: Given a dictionary d and a key k return the key that matches k.


Instruction:
Given the following Python 3 function, write the documentation
def merge_two_dicts(x: Dict, y: Dict) -> Dict:
    z = x.copy()
    z.update(y)
    return z

Response: Given two dicts merge them into a new dict as a shallow copy


Instruction:
Write a Python 3 function that can
rename a key in dictionary d from old to new in place.

Response:
def rename_key(d: Dict[str, Any], old: str, new: str) -> None:
    """
    Rename a key in dictionary ``d`` from ``old`` to ``new``, in place.
    """
    d[new] = d.pop(old)


Instruction:
Write a Python 3 function for
returning a copy of the dictionary d with the keys renamed according to mapping.

Response:
def rename_keys(d: Dict[str, Any], mapping: Dict[str, str]) -> Dict[str, Any]:
    """
    Returns a copy of the dictionary ``d`` with its keys renamed according to
    ``mapping``.

    Args:
        d: the starting dictionary
        mapping: a dictionary of the format ``{old_key_name: new_key_name}``

    Returns:
        a new dictionary

    Keys that are not in ``mapping`` are left unchanged.
    The input parameters are not modified.
    """
    result = {}  # type: Dict[str, Any]
    for k, v in d.items():
        if k in mapping:
            k = mapping[k]
        result[k] = v
    return result


Instruction:
Can you write a function in Python 3 where it
renames the keys in the dictionary d according to the mapping renames.

Response:
def rename_keys_in_dict(d: Dict[str, Any], renames: Dict[str, str]) -> None:
    """
    Renames, IN PLACE, the keys in ``d`` according to the mapping in
    ``renames``.

    Args:
        d: a dictionary to modify
        renames: a dictionary of the format ``{old_key_name: new_key_name}``

    See
    https://stackoverflow.com/questions/4406501/change-the-name-of-a-key-in-dictionary.
    """  # noqa
    for old_key, new_key in renames.items():
        if new_key == old_key:
            continue
        if old_key in d:
            if new_key in d:
                raise ValueError(
                    "rename_keys_in_dict: renaming {} -> {} but new key "
                    "already exists".format(repr(old_key), repr(new_key)))
            d[new_key] = d.pop(old_key)


Instruction:
Implement a function in Python 3 to
return a copy of d but with prefix prepended to its keys.

Response:
def prefix_dict_keys(d: Dict[str, Any], prefix: str) -> Dict[str, Any]:
    """
    Returns a dictionary that's a copy of as ``d`` but with ``prefix``
    prepended to its keys.
    """
    result = {}  # type: Dict[str, Any]
    for k, v in d.items():
        result[prefix + k] = v
    return result


Instruction:
Write a Python 3 function that can
take a k - > v mapping and returns a k - > v mapping.

Response:
def reversedict(d: Dict[Any, Any]) -> Dict[Any, Any]:
    """
    Takes a ``k -> v`` mapping and returns a ``v -> k`` mapping.
    """
    return {v: k for k, v in d.items()}


Instruction:
Given the following Python 3 function, write the documentation
def set_null_values_in_dict(d: Dict[str, Any],
                            null_literals: List[Any]) -> None:
    """
    Within ``d`` (in place), replace any values found in ``null_literals`` with
    ``None``.
    """
    if not null_literals:
        return
    # DO NOT add/delete values to/from a dictionary during iteration, but it
    # is OK to modify existing keys:
    #       https://stackoverflow.com/questions/6777485
    #       https://stackoverflow.com/questions/2315520
    #       https://docs.python.org/3/library/stdtypes.html#dict-views
    for k, v in d.items():
        if v in null_literals:
            d[k] = None

Response: Sets any null values found in null_literals with None.


Instruction:
Write a Python 3 script to
map keys in a list of objects to their corresponding values.

Response:
def map_keys_to_values(l: List[Any], d: Dict[Any, Any], default: Any = None,
                       raise_if_missing: bool = False,
                       omit_if_missing: bool = False) -> List[Any]:
    """
    The ``d`` dictionary contains a ``key -> value`` mapping.

    We start with a list of potential keys in ``l``, and return a list of
    corresponding values -- substituting ``default`` if any are missing,
    or raising :exc:`KeyError` if ``raise_if_missing`` is true, or omitting the
    entry if ``omit_if_missing`` is true.
    """
    result = []
    for k in l:
        if raise_if_missing and k not in d:
            raise ValueError("Missing key: " + repr(k))
        if omit_if_missing and k not in d:
            continue
        result.append(d.get(k, default))
    return result


Instruction:
How would you implement a function in Python 3 that
returns a dictionary that contains the changes made to d1 to d2.

Response:
def dict_diff(d1: Dict[Any, Any], d2: Dict[Any, Any],
              deleted_value: Any = None) -> Dict[Any, Any]:
    """
    Returns a representation of the changes that need to be made to ``d1`` to
    create ``d2``.

    Args:
        d1: a dictionary
        d2: another dictionary
        deleted_value: value to use for deleted keys; see below

    Returns:
        dict: a dictionary of the format ``{k: v}`` where the ``k``/``v`` pairs
        are key/value pairs that are absent from ``d1`` and present in ``d2``,
        or present in both but with different values (in which case the ``d2``
        value is shown). If a key ``k`` is present in ``d1`` but absent in
        ``d2``, the result dictionary has the entry ``{k: deleted_value}``.

    """
    changes = {k: v for k, v in d2.items()
               if k not in d1 or d2[k] != d1[k]}
    for k in d1.keys():
        if k not in d2:
            changes[k] = deleted_value
    return changes


Instruction:
Can you create a Python 3 function that
deletes keys from a dictionary in place.

Response:
def delete_keys(d: Dict[Any, Any],
                keys_to_delete: List[Any],
                keys_to_keep: List[Any]) -> None:
    """
    Deletes keys from a dictionary, in place.

    Args:
        d:
            dictonary to modify
        keys_to_delete:
            if any keys are present in this list, they are deleted...
        keys_to_keep:
            ... unless they are present in this list.
    """
    for k in keys_to_delete:
        if k in d and k not in keys_to_keep:
            del d[k]


Instruction:
Can you tell what is the following Python 3 function doing
def process_bind_param(self, value: Optional[List[str]],
                           dialect: Dialect) -> str:
        """Convert things on the way from Python to the database."""
        retval = self._strlist_to_dbstr(value)
        return retval

Response: Convert things on the way from Python to database.


Instruction:
Make a summary of the following Python 3 code
def process_result_value(self, value: Optional[str],
                             dialect: Dialect) -> List[str]:
        """Convert things on the way from the database to Python."""
        retval = self._dbstr_to_strlist(value)
        return retval

Response: Convert things on the way from the database to Python.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def process_literal_param(self, value: Optional[List[int]],
                              dialect: Dialect) -> str:
        """Convert things on the way from Python to the database."""
        retval = self._intlist_to_dbstr(value)
        return retval

Response: Convert things on the way from Python to the database.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def process_result_value(self, value: Optional[str],
                             dialect: Dialect) -> List[int]:
        """Convert things on the way from the database to Python."""
        retval = self._dbstr_to_intlist(value)
        return retval

Response: Convert things on the way from the database to Python.


Instruction:
Given the following Python 3 function, write the documentation
def set_timing(self, timing: bool, reset: bool = False) -> None:
        self._timing = timing
        if reset:
            self.reset()

Response: Set the timing parameter.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def start(self, name: str, increment_count: bool = True) -> None:
        if not self._timing:
            return
        now = get_now_utc_pendulum()

        # If we were already timing something else, pause that.
        if self._stack:
            last = self._stack[-1]
            self._totaldurations[last] += now - self._starttimes[last]

        # Start timing our new thing
        if name not in self._starttimes:
            self._totaldurations[name] = datetime.timedelta()
            self._count[name] = 0
        self._starttimes[name] = now
        if increment_count:
            self._count[name] += 1
        self._stack.append(name)

Response: Start a named timer.


Instruction:
Create a Python 3 function to
stop a named timer.

Response:
def stop(self, name: str) -> None:
        """
        Stop a named timer.

        Args:
            name: timer to stop
        """
        if not self._timing:
            return
        now = get_now_utc_pendulum()

        # Validity check
        if not self._stack:
            raise AssertionError("MultiTimer.stop() when nothing running")
        if self._stack[-1] != name:
            raise AssertionError(
                "MultiTimer.stop({}) when {} is running".format(
                    repr(name), repr(self._stack[-1])))

        # Finish what we were asked to
        self._totaldurations[name] += now - self._starttimes[name]
        self._stack.pop()

        # Now, if we were timing something else before we started "name",
        # resume...
        if self._stack:
            last = self._stack[-1]
            self._starttimes[last] = now


Instruction:
Can you create a Python 3 function that
plots an attitude measurement on an object.

Response:
def girdle_error(ax, fit, **kwargs):
    """
    Plot an attitude measurement on an `mplstereonet` axes object.
    """
    vertices = []
    codes = []
    for sheet in ('upper','lower'):
        err = plane_errors(fit.axes, fit.covariance_matrix,
                sheet=sheet)
        lonlat = N.array(err)
        lonlat *= -1
        n = len(lonlat)
        if sheet == 'lower':
            lonlat = lonlat[::-1]
        vertices += list(lonlat)
        codes.append(Path.MOVETO)
        codes += [Path.LINETO]*(n-1)

    plot_patch(ax, vertices, codes, **kwargs)


Instruction:
How would you implement a function in Python 3 that
plots the error to the pole to a plane on a matplotlibstereonet object.

Response:
def pole_error(ax, fit, **kwargs):
    """
    Plot the error to the pole to a plane on a `mplstereonet`
    axis object.
    """
    ell = normal_errors(fit.axes, fit.covariance_matrix)
    lonlat = -N.array(ell)
    n = len(lonlat)
    codes = [Path.MOVETO]
    codes += [Path.LINETO]*(n-1)
    vertices = list(lonlat)

    plot_patch(ax, vertices, codes, **kwargs)


Instruction:
Create a Python 3 function to
ping a host using OS tools.

Response:
def ping(hostname: str, timeout_s: int = 5) -> bool:
    """
    Pings a host, using OS tools.

    Args:
        hostname: host name or IP address
        timeout_s: timeout in seconds

    Returns:
        was the ping successful?

    """
    if sys.platform == "win32":
        timeout_ms = timeout_s * 1000
        args = [
            "ping",
            hostname,
            "-n", "1",  # ping count
            "-w", str(timeout_ms),  # timeout
        ]
    elif sys.platform.startswith('linux'):
        args = [
            "ping",
            hostname,
            "-c", "1",  # ping count
            "-w", str(timeout_s),  # timeout
        ]
    else:
        raise AssertionError("Don't know how to ping on this operating system")
    proc = subprocess.Popen(args,
                            stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    proc.communicate()
    retcode = proc.returncode
    return retcode == 0


Instruction:
Create a Python 3 function to
download a URL to a file.

Response:
def download(url: str, filename: str,
             skip_cert_verify: bool = True) -> None:
    """
    Downloads a URL to a file.

    Args:
        url: URL to download from
        filename: file to save to
        skip_cert_verify: skip SSL certificate check?
    """
    log.info("Downloading from {} to {}", url, filename)

    # urllib.request.urlretrieve(url, filename)
    # ... sometimes fails (e.g. downloading
    # https://www.openssl.org/source/openssl-1.1.0g.tar.gz under Windows) with:
    # ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:777)  # noqa
    # ... due to this certificate root problem (probably because OpenSSL
    #     [used by Python] doesn't play entirely by the same rules as others?):
    # https://stackoverflow.com/questions/27804710
    # So:

    ctx = ssl.create_default_context()  # type: ssl.SSLContext
    if skip_cert_verify:
        log.debug("Skipping SSL certificate check for " + url)
        ctx.check_hostname = False
        ctx.verify_mode = ssl.CERT_NONE
    with urllib.request.urlopen(url, context=ctx) as u, open(filename,
                                                             'wb') as f:  # noqa
        f.write(u.read())


Instruction:
Can you tell what is the following Python 3 function doing
def gen_binary_files_from_urls(
        urls: Iterable[str],
        on_disk: bool = False,
        show_info: bool = True) -> Generator[BinaryIO, None, None]:
    """
    Generate binary files from a series of URLs (one per URL).

    Args:
        urls: iterable of URLs
        on_disk: if ``True``, yields files that are on disk (permitting
            random access); if ``False``, yields in-memory files (which will
            not permit random access)
        show_info: show progress to the log?

    Yields:
        files, each of type :class:`BinaryIO`

    """
    for url in urls:
        if on_disk:
            # Necessary for e.g. zip processing (random access)
            with tempfile.TemporaryDirectory() as tmpdir:
                filename = os.path.join(tmpdir, "tempfile")
                download(url=url, filename=filename)
                with open(filename, 'rb') as f:
                    yield f
        else:
            if show_info:
                log.info("Reading from URL: {}", url)
            with urllib.request.urlopen(url) as f:
                yield f
        if show_info:
            log.info("... finished reading from URL: {}", url)

Response: Generates binary files from a series of URLs.


Instruction:
Given the following Python 3 function, write the documentation
def find_nth(s: str, x: str, n: int = 0, overlap: bool = False) -> int:
    length_of_fragment = 1 if overlap else len(x)
    i = -length_of_fragment
    for _ in range(n + 1):
        i = s.find(x, i + length_of_fragment)
        if i < 0:
            break
    return i

Response: Finds the position of nth occurrence of x in s or - 1 if there isn t one.


Instruction:
Can you tell what is the following Python 3 function doing
def split_string(x: str, n: int) -> List[str]:
    # https://stackoverflow.com/questions/9475241/split-string-every-nth-character  # noqa
    return [x[i:i+n] for i in range(0, len(x), n)]

Response: Split string into chunks of length n


Instruction:
Can you generate a brief explanation for the following Python 3 code
def multiple_replace(text: str, rep: Dict[str, str]) -> str:
    rep = dict((re.escape(k), v) for k, v in rep.items())
    pattern = re.compile("|".join(rep.keys()))
    return pattern.sub(lambda m: rep[re.escape(m.group(0))], text)

Response: Returns a version of text with the keys of rep replaced by their values.


Instruction:
Can you write a function in Python 3 where it
returns a list of strings produced by applying multiple_replace to every string in stringlist.

Response:
def replace_in_list(stringlist: Iterable[str],
                    replacedict: Dict[str, str]) -> List[str]:
    """
    Returns a list produced by applying :func:`multiple_replace` to every
    string in ``stringlist``.

    Args:
        stringlist: list of source strings
        replacedict: dictionary mapping "original" to "replacement" strings

    Returns:
        list of final strings

    """
    newlist = []
    for fromstring in stringlist:
        newlist.append(multiple_replace(fromstring, replacedict))
    return newlist


Instruction:
Write a Python 3 script for
mangling unicode to ASCII losing accents etc. in the process.

Response:
def mangle_unicode_to_ascii(s: Any) -> str:
    """
    Mangle unicode to ASCII, losing accents etc. in the process.
    """
    # http://stackoverflow.com/questions/1207457
    if s is None:
        return ""
    if not isinstance(s, str):
        s = str(s)
    return (
        unicodedata.normalize('NFKD', s)
                   .encode('ascii', 'ignore')  # gets rid of accents
                   .decode('ascii')  # back to a string
    )


Instruction:
How would you explain what the following Python 3 function does
def strnum(prefix: str, num: int, suffix: str = "") -> str:
    return "{}{}{}".format(prefix, num, suffix)

Response: Makes a string of the format <prefix><number><suffix >.


Instruction:
Implement a function in Python 3 to
make a string of the format <prefix><number><suffix > for every number in numbers and returns them as a list.

Response:
def strnumlist(prefix: str, numbers: List[int], suffix: str = "") -> List[str]:
    """
    Makes a string of the format ``<prefix><number><suffix>`` for every number
    in ``numbers``, and returns them as a list.
    """
    return ["{}{}{}".format(prefix, num, suffix) for num in numbers]


Instruction:
How would you code a function in Python 3 to
make a string of the format <prefix><number><suffix > for every number from first to last inclusive.

Response:
def strseq(prefix: str, first: int, last: int, suffix: str = "") -> List[str]:
    """
    Makes a string of the format ``<prefix><number><suffix>`` for every number
    from ``first`` to ``last`` inclusive, and returns them as a list.
    """
    return [strnum(prefix, n, suffix) for n in range(first, last + 1)]


Instruction:
Can you implement a function in Python 3 that
calculates the variance of a bootstrap .

Response:
def aligned_residuals(pca):
    """
    Plots error components along with bootstrap
    resampled error surface. Provides another
    statistical method to estimate the variance
    of a dataset.
    """
    A = pca.rotated()
    fig, axes = P.subplots(2,1,
            sharex=True, frameon=False)
    fig.subplots_adjust(hspace=0, wspace=0.1)
    kw = dict(c="#555555", s=40, alpha=0.5)

    #lengths = attitude.pca.singular_values[::-1]
    lengths = (A[:,i].max()-A[:,i].min() for i in range(3))

    titles = (
        "Long cross-section (axis 3 vs. axis 1)",
        "Short cross-section (axis 3 vs. axis 2)")

    for title,ax,(a,b) in zip(titles,axes,
            [(0,2),(1,2)]):

        seaborn.regplot(A[:,a], A[:,b], ax=ax)
        ax.text(0,1,title,
            verticalalignment='top',
            transform=ax.transAxes)
        ax.autoscale(tight=True)
        for spine in ax.spines.itervalues():
            spine.set_visible(False)
    ax.set_xlabel("Meters")
    return fig


Instruction:
Create a Python 3 function to
return the singleton instance of the class.

Response:
def get_instance(self):
        """
        Returns the singleton instance. Upon its first call, it creates a
        new instance of the decorated class and calls its `__init__` method.
        On all subsequent calls, the already created instance is returned.
        """
        try:
            return self._instance
        except AttributeError:
            self._instance = self._decorated()
            return self._instance


Instruction:
Make a summary of the following Python 3 code
def mapper_init(self):
        self.lookup = CachedMetroLookup(precision=GEOHASH_PRECISION)
        self.extractor = WordExtractor()

Response: build local spatial index of US metro areas


Instruction:
Write a Python 3 function for
establishing connection to MongoDB instance and initialize the object

Response:
def reducer_init_output(self):
        """ establish connection to MongoDB """
        try:
            self.mongo = MongoGeo(db=DB, collection=COLLECTION, timeout=MONGO_TIMEOUT)
        except ServerSelectionTimeoutError:
            # failed to connect to running MongoDB instance
            self.mongo = None


Instruction:
Can you tell what is the following Python 3 function doing
def save(self, *args, **kwargs):
        slug = "{}:{}".format(self.level.uid, self.code)
        if self.parent:
            self.uid = "{}_{}".format(self.parent.uid, slug)
        else:
            self.uid = slug
        self.slug = uuslug(
            self.name, instance=self, max_length=100, separator="-", start_no=2
        )
        super(Division, self).save(*args, **kwargs)

Response: Save the instance to the database.


Instruction:
How would you explain what the following Python 3 function does
def add_intersecting(self, division, intersection=None, symm=True):
        relationship, created = IntersectRelationship.objects.update_or_create(
            from_division=self,
            to_division=division,
            defaults={"intersection": intersection},
        )
        if symm:
            division.add_intersecting(self, None, False)
        return relationship

Response: Adds paired relationships between intersecting divisions.


Instruction:
How would you implement a function in Python 3 that
removes paired relationships between intersecting divisions

Response:
def remove_intersecting(self, division, symm=True):
        """Removes paired relationships between intersecting divisions"""
        IntersectRelationship.objects.filter(
            from_division=self, to_division=division
        ).delete()
        if symm:
            division.remove_intersecting(self, False)


Instruction:
Make a summary of the following Python 3 code
def set_intersection(self, division, intersection):
        IntersectRelationship.objects.filter(
            from_division=self, to_division=division
        ).update(intersection=intersection)

Response: Set intersection percentage of intersecting divisions.


Instruction:
Create a Python 3 function for
getting intersection percentage of intersecting divisions.

Response:
def get_intersection(self, division):
        """Get intersection percentage of intersecting divisions."""
        try:
            return IntersectRelationship.objects.get(
                from_division=self, to_division=division
            ).intersection
        except ObjectDoesNotExist:
            raise Exception("No intersecting relationship with that division.")


Instruction:
Can you create a Python 3 function that
launches a job into the SLURM environment.

Response:
def launch_slurm(jobname: str,
                 cmd: str,
                 memory_mb: int,
                 project: str,
                 qos: str,
                 email: str,
                 duration: timedelta,
                 tasks_per_node: int,
                 cpus_per_task: int,
                 partition: str = "",
                 modules: List[str] = None,
                 directory: str = os.getcwd(),
                 encoding: str = "ascii") -> None:
    """
    Launch a job into the SLURM environment.

    Args:
        jobname: name of the job
        cmd: command to be executed
        memory_mb: maximum memory requirement per process (Mb)
        project: project name
        qos: quality-of-service name
        email: user's e-mail address
        duration: maximum duration per job
        tasks_per_node: tasks per (cluster) node
        cpus_per_task: CPUs per task
        partition: cluster partition name
        modules: SLURM modules to load
        directory: directory to change to
        encoding: encoding to apply to launch script as sent to ``sbatch``
    """
    if partition:
        partition_cmd = "#SBATCH -p {}".format(partition)
    else:
        partition_cmd = ""
    if modules is None:
        modules = ["default-wbic"]

    log.info("Launching SLURM job: {}", jobname)
    script = """#!/bin/bash

#! Name of the job:
#SBATCH -J {jobname}

#! Which project should jobs run under:
#SBATCH -A {project}

#! What QoS [Quality of Service] should the job run in?
#SBATCH --qos={qos}

#! How much resource should be allocated?
#SBATCH --tasks-per-node={tasks_per_node}
#SBATCH --cpus-per-task={cpus_per_task}

#! Memory requirements
#SBATCH --mem={memory_mb}

#! How much wall-clock time will be required?
#SBATCH --time={duration}

#! What e-mail address to use for notifications?
#SBATCH --mail-user={email}

#! What types of email messages do you wish to receive?
#SBATCH --mail-type=ALL

#! Uncomment this to prevent the job from being requeued (e.g. if
#! interrupted by node failure or system downtime):
#! SBATCH --no-requeue

#! Partition
{partition_cmd}

#! sbatch directives end here (put any additional directives above this line)

#! ############################################################
#! Modify the settings below to specify the application's environment, location
#! and launch method:

#! Optionally modify the environment seen by the application
#! (note that SLURM reproduces the environment at submission irrespective of ~/.bashrc):
. /etc/profile.d/modules.sh                # Leave this line (enables the module command)
module purge                               # Removes all modules still loaded
module load {modules}                      # Basic one, e.g. default-wbic, is REQUIRED - loads the basic environment

#! Insert additional module load commands after this line if needed:

#! Full path to your application executable:
application="hostname"

#! Run options for the application:
options=""

#! Work directory (i.e. where the job will run):
workdir="$SLURM_SUBMIT_DIR"  # The value of SLURM_SUBMIT_DIR sets workdir to the directory
                             # in which sbatch is run.

#! Are you using OpenMP (NB this is **unrelated to OpenMPI**)? If so increase this
#! safe value to no more than 24:
export OMP_NUM_THREADS=24

# Command line to be submited by SLURM:
CMD="{cmd}"

###############################################################
### You should not have to change anything below this line ####
###############################################################

cd $workdir
echo -e "Changed directory to `pwd`.\n"

JOBID=$SLURM_JOB_ID

echo -e "JobID: $JOBID\n======"
echo "Time: `date`"
echo "Running on master node: `hostname`"
echo "Current directory: `pwd`"

if [ "$SLURM_JOB_NODELIST" ]; then
    #! Create a machine file:
    export NODEFILE=`/usr/bin/generate_pbs_nodefile`
    cat $NODEFILE | uniq > machine.file.$JOBID
    echo -e "\nNodes allocated:\n================"
    echo `cat machine.file.$JOBID | sed -e 's/\..*$//g'`
fi

echo -e "\nExecuting command:\n==================\n$CMD\n"

eval $CMD
    """.format(  # noqa
        cmd=cmd,
        cpus_per_task=cpus_per_task,
        duration=strfdelta(duration, SLURM_TIMEDELTA_FMT),
        email=email,
        jobname=jobname,
        memory_mb=memory_mb,
        modules=" ".join(modules),
        partition_cmd=partition_cmd,
        project=project,
        qos=qos,
        tasks_per_node=tasks_per_node,
    )
    cmdargs = ["sbatch"]
    with pushd(directory):
        p = Popen(cmdargs, stdin=PIPE)
        p.communicate(input=script.encode(encoding))


Instruction:
Make a summary of the following Python 3 code
def launch_cambridge_hphi(
        jobname: str,
        cmd: str,
        memory_mb: int,
        qos: str,
        email: str,
        duration: timedelta,
        cpus_per_task: int,
        project: str = "hphi",
        tasks_per_node: int = 1,
        partition: str = "wbic-cs",  # 2018-02: was "wbic", now "wbic-cs"
        modules: List[str] = None,
        directory: str = os.getcwd(),
        encoding: str = "ascii") -> None:
    """
    Specialization of :func:`launch_slurm` (q.v.) with defaults for the
    University of Cambridge WBIC HPHI.
    """
    if modules is None:
        modules = ["default-wbic"]
    launch_slurm(
        cmd=cmd,
        cpus_per_task=cpus_per_task,
        directory=directory,
        duration=duration,
        email=email,
        encoding=encoding,
        jobname=jobname,
        memory_mb=memory_mb,
        modules=modules,
        partition=partition,
        project=project,
        qos=qos,
        tasks_per_node=tasks_per_node,
    )

Response: Launch a Cambridge HPHI.


Instruction:
Write a Python 3 script to
convert a drug name to a : class :. Drug class.

Response:
def get_drug(drug_name: str,
             name_is_generic: bool = False,
             include_categories: bool = False) -> Optional[Drug]:
    """
    Converts a drug name to a :class:`.Drug` class.

    If you already have the generic name, you can get the Drug more
    efficiently by setting ``name_is_generic=True``.

    Set ``include_categories=True`` to include drug categories (such as
    tricyclics) as well as individual drugs.
    """
    drug_name = drug_name.strip().lower()
    if name_is_generic:
        drug = DRUGS_BY_GENERIC_NAME.get(drug_name)  # type: Optional[Drug]
        if drug is not None and drug.category_not_drug and not include_categories:  # noqa
            return None
        return drug
    else:
        for d in DRUGS:
            if d.name_matches(drug_name):
                return d
        return None


Instruction:
Write a Python 3 function for
converting a drug name to its generic equivalent.

Response:
def drug_name_to_generic(drug_name: str,
                         unknown_to_default: bool = False,
                         default: str = None,
                         include_categories: bool = False) -> str:
    """
    Converts a drug name to the name of its generic equivalent.
    """
    drug = get_drug(drug_name, include_categories=include_categories)
    if drug is not None:
        return drug.generic_name
    return default if unknown_to_default else drug_name


Instruction:
Write a Python 3 script to
convert a list of drug names to their generic equivalents.

Response:
def drug_names_to_generic(drugs: List[str],
                          unknown_to_default: bool = False,
                          default: str = None,
                          include_categories: bool = False) -> List[str]:
    """
    Converts a list of drug names to their generic equivalents.

    The arguments are as for :func:`drug_name_to_generic` but this function
    handles a list of drug names rather than a single one.

    Note in passing the following conversion of blank-type representations from
    R via ``reticulate``, when using e.g. the ``default`` parameter and storing
    results in a ``data.table()`` character column:

    .. code-block:: none

        ------------------------------  ----------------
        To Python                       Back from Python
        ------------------------------  ----------------
        [not passed, so Python None]    "NULL"
        NULL                            "NULL"
        NA_character_                   "NA"
        NA                              TRUE (logical)
        ------------------------------  ----------------

    """
    return [
        drug_name_to_generic(drug,
                             unknown_to_default=unknown_to_default,
                             default=default,
                             include_categories=include_categories)
        for drug in drugs
    ]


Instruction:
How would you implement a function in Python 3 that
determines whether a drug instance matches the specified criteria.

Response:
def drug_matches_criteria(drug: Drug, **criteria: Dict[str, bool]) -> bool:
    """
    Determines whether a drug, passed as an instance of :class:`.Drug`, matches
    the specified criteria.

    Args:
        drug: a :class:`.Drug` instance
        criteria: ``name=value`` pairs to match against the attributes of
            the :class:`Drug` class. For example, you can include keyword
            arguments like ``antidepressant=True``.
    """
    for attribute, value in criteria.items():
        if getattr(drug, attribute) != value:
            return False
    return True


Instruction:
Can you generate a brief explanation for the following Python 3 code
def all_drugs_where(sort=True,
                    include_categories: bool = False,
                    **criteria: Dict[str, bool]) -> List[Drug]:
    """
    Find all drugs matching the specified criteria (see
    :func:`drug_matches_criteria`). If ``include_categories`` is true, then
    drug categories (like "tricyclics") are included as well as individual
    drugs.

    Pass keyword arguments such as

    .. code-block:: python

        from cardinal_pythonlib.psychiatry.drugs import *
        non_ssri_antidep = all_drugs_where(antidepressant=True, ssri=False)
        print([d.generic_name for d in non_ssri_antidep])
        conventional_antidep = all_drugs_where(conventional_antidepressant=True)
        print([d.generic_name for d in conventional_antidep])
    """
    matching_drugs = []  # type: List[Drug]
    for drug in DRUGS:
        if drug.category_not_drug and not include_categories:
            continue
        if drug_matches_criteria(drug, **criteria):
            matching_drugs.append(drug)
    if sort:
        matching_drugs.sort(key=lambda d: d.generic_name)
    return matching_drugs

Response: Returns a list of all the drugs that match the criteria.


Instruction:
Given the following Python 3 function, write the documentation
def drug_name_matches_criteria(drug_name: str,
                               name_is_generic: bool = False,
                               include_categories: bool = False,
                               **criteria: Dict[str, bool]) -> bool:
    """
    Establish whether a single drug, passed by name, matches the specified
    criteria. See :func:`drug_matches_criteria`.
    """
    drug = get_drug(drug_name, name_is_generic)
    if drug is None:
        return False
    if drug.category_not_drug and not include_categories:
        return False
    return drug_matches_criteria(drug, **criteria)

Response: Determines whether a single drug passed by name matches the specified criteria.


Instruction:
Create a Python 3 function to
establish whether multiple drugs passed as a list of drug names each racket matches the specified criteria.

Response:
def drug_names_match_criteria(drug_names: List[str],
                              names_are_generic: bool = False,
                              include_categories: bool = False,
                              **criteria: Dict[str, bool]) -> List[bool]:
    """
    Establish whether multiple drugs, passed as a list of drug names, each
    matches the specified criteria. See :func:`drug_matches_criteria`.
    """
    return [
        drug_name_matches_criteria(
            dn,
            name_is_generic=names_are_generic,
            include_categories=include_categories,
            **criteria)
        for dn in drug_names
    ]


Instruction:
How would you implement a function in Python 3 that
returns the regex text for this drug.

Response:
def regex_text(self) -> str:
        """
        Return regex text (yet to be compiled) for this drug.
        """
        if self._regex_text is None:
            possibilities = []  # type: List[str]
            for p in list(set(self.all_generics + self.alternatives)):
                if self.add_preceding_word_boundary and not p.startswith(WB):
                    p = WB + p
                if self.add_preceding_wildcards and not p.startswith(WILDCARD):
                    p = WILDCARD + p
                if self.add_following_wildcards and not p.endswith(WILDCARD):
                    p = p + WILDCARD
                possibilities.append(p)
            self._regex_text = "|".join("(?:" + x + ")" for x in possibilities)
        return self._regex_text


Instruction:
Can you generate a brief explanation for the following Python 3 code
def regex(self) -> Pattern:
        if self._regex is None:
            self._regex = re.compile(self.regex_text,
                                     re.IGNORECASE | re.DOTALL)
        return self._regex

Response: Returns a compiled regex for this drug.


Instruction:
Implement a Python 3 function for
converting a regular expression text to a reasonably close fragment of SQL string.

Response:
def regex_to_sql_like(regex_text: str,
                          single_wildcard: str = "_",
                          zero_or_more_wildcard: str = "%") -> List[str]:
        """
        Converts regular expression text to a reasonably close fragment
        for the SQL ``LIKE`` operator.

        NOT PERFECT, but works for current built-in regular expressions.

        Args:
            regex_text: regular expression text to work with
            single_wildcard: SQL single wildcard, typically an underscore
            zero_or_more_wildcard: SQL "zero/one/many" wildcard, probably always
                a percent symbol

        Returns:
            string for an SQL string literal

        Raises:
            :exc:`ValueError` for some regex text that it doesn't understand
            properly
        """
        def append_to_all(new_content: str) -> None:
            nonlocal results
            results = [r + new_content for r in results]

        def split_and_append(new_options: List[str]) -> None:
            nonlocal results
            newresults = []  # type: List[str]
            for option in new_options:
                newresults.extend([r + option for r in results])
            results = newresults

        def deduplicate_wildcards(text: str) -> str:
            while zero_or_more_wildcard + zero_or_more_wildcard in text:
                text = text.replace(
                    zero_or_more_wildcard + zero_or_more_wildcard,
                    zero_or_more_wildcard)
            return text

        # Basic processing
        working = regex_text  # strings are immutable
        results = [zero_or_more_wildcard]  # start with a wildcard

        while working:
            if working.startswith(".*"):
                # e.g. ".*ozapi"
                append_to_all(zero_or_more_wildcard)
                working = working[2:]
            elif working.startswith("["):
                # e.g. "[io]peridol"
                close_bracket = working.index("]")  # may raise
                bracketed = working[1:close_bracket]
                option_groups = bracketed.split("|")
                options = [c for group in option_groups for c in group]
                split_and_append(options)
                working = working[close_bracket + 1:]
            elif len(working) > 1 and working[1] == "?":
                # e.g. "r?azole"
                split_and_append(["", working[0]])
                # ... regex "optional character"
                # ... SQL: some results with a single wildcard, some without
                working = working[2:]
            elif working.startswith("."):
                # single character wildcard
                append_to_all(single_wildcard)
                working = working[1:]
            else:
                append_to_all(working[0])
                working = working[1:]
        append_to_all(zero_or_more_wildcard)  # end with a wildcard

        # Remove any duplicate (consecutive) % wildcards:
        results = [deduplicate_wildcards(r) for r in results]

        # Done
        return results


Instruction:
Can you create a Python 3 function that
returns all the SQL - like fragments that are used to compare the database column names with the SQL - LIKE operator.

Response:
def sql_like_fragments(self) -> List[str]:
        """
        Returns all the string literals to which a database column should be
        compared using the SQL ``LIKE`` operator, to match this drug.

        This isn't as accurate as the regex, but ``LIKE`` can do less.

        ``LIKE`` uses the wildcards ``?`` and ``%``.
        """
        if self._sql_like_fragments is None:
            self._sql_like_fragments = []
            for p in list(set(self.all_generics + self.alternatives)):
                self._sql_like_fragments.extend(self.regex_to_sql_like(p))
        return self._sql_like_fragments


Instruction:
Can you generate the documentation for the following Python 3 function
def name_matches(self, name: str) -> bool:
        return bool(self.regex.match(name))

Response: Determines whether the given name matches our knowledge of any of the related objects.


Instruction:
Can you generate the documentation for the following Python 3 function
def sql_column_like_drug(self, column_name: str) -> str:
        clauses = [
            "{col} LIKE {fragment}".format(
                col=column_name,
                fragment=sql_string_literal(f))
            for f in self.sql_like_fragments
        ]
        return "({})".format(" OR ".join(clauses))

Response: Returns the SQL like clause for the drug column_name.


Instruction:
Given the following Python 3 function, write the documentation
def quaternion(vector, angle):
    return N.cos(angle/2)+vector*N.sin(angle/2)

Response: Returns the unit quaternion for a vector and an angle.


Instruction:
Can you implement a function in Python 3 that
returns a parameterized set of vectors defining an ellipse.

Response:
def ellipse(n=1000, adaptive=False):
    """
    Get a parameterized set of vectors defining
    ellipse for a major and minor axis length.
    Resulting vector bundle has major axes
    along axes given.
    """
    u = N.linspace(0,2*N.pi,n)
    # Get a bundle of vectors defining
    # a full rotation around the unit circle
    return N.array([N.cos(u),N.sin(u)]).T


Instruction:
Implement a function in Python 3 to
return major axes of error ellipse or rescaled using chi2 test statistic

Response:
def scale_errors(cov_axes, confidence_level=0.95):
    """
    Returns major axes of error ellipse or
    hyperbola, rescaled using chi2 test statistic
    """
    dof = len(cov_axes)
    x2t = chi2.ppf(confidence_level,dof)
    return N.sqrt(x2t*cov_axes)


Instruction:
Make a summary of the following Python 3 code
def normal_errors(axes, covariance_matrix, **kwargs):
    level = kwargs.pop('level',1)
    traditional_layout = kwargs.pop('traditional_layout',True)
    d = N.diagonal(covariance_matrix)
    ell = ellipse(**kwargs)

    if axes[2,2] < 0:
        axes *= -1

    # Not sure where this factor comes from but it
    # seems to make things work better
    c1 = 2
    axis_lengths = d[:2]
    f = N.linalg.norm(
        ell*axis_lengths,axis=1)

    e0 = -ell.T*d[2]*c1
    e = N.vstack((e0,f))

    _ = dot(e.T,axes).T

    if traditional_layout:
        lon,lat = stereonet_math.cart2sph(_[2],_[0],-_[1])
    else:
        lon,lat = stereonet_math.cart2sph(-_[1],_[0],_[2])
    return list(zip(lon,lat))

Response: Returns a list of lon lat values for a set of normal axes.


Instruction:
Here you have a function in Python 3, explain what it does
def plane_errors(axes, covariance_matrix, sheet='upper',**kwargs):

    level = kwargs.pop('level',1)
    traditional_layout = kwargs.pop('traditional_layout',True)

    d = N.sqrt(covariance_matrix)

    ell = ellipse(**kwargs)
    bundle = dot(ell, d[:2])
    res = d[2]*level

    # Switch hemispheres if PCA is upside-down
    # Normal vector is always correctly fit
    #if traditional_layout:
    #if axes[2,2] > 0:

    if axes[2,2] > 0:
        res *= -1

    if sheet == 'upper':
        bundle += res
    elif sheet == 'lower':
        bundle -= res

    _ = dot(bundle,axes).T

    if traditional_layout:
        lon,lat = stereonet_math.cart2sph(_[2],_[0],_[1])
    else:
        lon,lat = stereonet_math.cart2sph(-_[1],_[0],_[2])

    return list(zip(lon,lat))

Response: Returns a list of lon lat values for each plane in the diagram.


Instruction:
Explain what the following Python 3 code does
def iterative_plane_errors(axes,covariance_matrix, **kwargs):
    sheet = kwargs.pop('sheet','upper')
    level = kwargs.pop('level',1)
    n = kwargs.pop('n',100)

    cov = N.sqrt(N.diagonal(covariance_matrix))
    u = N.linspace(0, 2*N.pi, n)

    scales = dict(upper=1,lower=-1,nominal=0)
    c1 = scales[sheet]
    c1 *= -1 # We assume upper hemisphere
    if axes[2,2] < 0:
        c1 *= -1

    def sdot(a,b):
        return sum([i*j for i,j in zip(a,b)])

    def step_func(a):
        e = [
            N.cos(a)*cov[0],
            N.sin(a)*cov[1],
            c1*cov[2]]
        d = [sdot(e,i)
            for i in axes.T]
        x,y,z = d[2],d[0],d[1]
        r = N.sqrt(x**2 + y**2 + z**2)
        lat = N.arcsin(z/r)
        lon = N.arctan2(y, x)
        return lon,lat

    # Get a bundle of vectors defining
    # a full rotation around the unit circle
    return N.array([step_func(i)
        for i in u])

Response: This function computes an iterative version of pca. plane_errors which computes an error surface for a plane.


Instruction:
Can you generate the documentation for the following Python 3 function
def quote_identifier_if_required(cls, identifier: str,
                                     debug_force_quote: bool = False) -> str:
        """
        Transforms a SQL identifier (such as a column name) into a version
        that is quoted if required (or, with ``debug_force_quote=True``, is
        quoted regardless).
        """
        if debug_force_quote:
            return cls.quote_identifier(identifier)
        if cls.is_quoted(identifier):
            return identifier
        if cls.requires_quoting(identifier):
            return cls.quote_identifier(identifier)
        return identifier

Response:
Transforms a SQL identifier into a version
        that is quoted if required.


Instruction:
Write a Python 3 function that can
add points and converts to topojson string.

Response:
def to_topojson(self):
        """Adds points and converts to topojson string."""
        topojson = self.topojson
        topojson["objects"]["points"] = {
            "type": "GeometryCollection",
            "geometries": [point.to_topojson() for point in self.points.all()],
        }
        return json.dumps(topojson)


Instruction:
Create a Python 3 function for
posting an element to Netuitive.

Response:
def post(self, element):
        """
            :param element: Element to post to Netuitive
            :type element: object
        """

        try:

            if self.disabled is True:
                element.clear_samples()
                logging.error('Posting has been disabled. '
                              'See previous errors for details.')
                return(False)

            if element.id is None:
                raise Exception('element id is not set')

            element.merge_metrics()
            payload = json.dumps(
                [element], default=lambda o: o.__dict__, sort_keys=True)
            logging.debug(payload)

            headers = {'Content-Type': 'application/json',
                       'User-Agent': self.agent}
            request = urllib2.Request(
                self.dataurl, data=payload, headers=headers)
            resp = urllib2.urlopen(request)
            logging.debug("Response code: %d", resp.getcode())

            resp.close()

            self.post_error_count = 0

            return(True)

        except urllib2.HTTPError as e:
            logging.debug("Response code: %d", e.code)

            if e.code in self.kill_codes:
                self.disabled = True

                logging.exception('Posting has been disabled.'
                                  'See previous errors for details.')
            else:
                self.post_error_count += 1
                if self.post_error_count > self.max_post_errors:
                    element.clear_samples()

                logging.exception(
                    'error posting payload to api ingest endpoint (%s): %s',
                    self.dataurl, e)

        except Exception as e:
            self.post_error_count += 1
            if self.post_error_count > self.max_post_errors:
                element.clear_samples()  # pragma: no cover

            logging.exception(
                'error posting payload to api ingest endpoint (%s): %s',
                self.dataurl, e)


Instruction:
Implement a function in Python 3 to
post an event to Netuitive .

Response:
def post_event(self, event):
        """
            :param event: Event to post to Netuitive
            :type event: object
        """

        if self.disabled is True:
            logging.error('Posting has been disabled. '
                          'See previous errors for details.')
            return(False)

        payload = json.dumps(
            [event], default=lambda o: o.__dict__, sort_keys=True)
        logging.debug(payload)
        try:
            headers = {'Content-Type': 'application/json',
                       'User-Agent': self.agent}
            request = urllib2.Request(
                self.eventurl, data=payload, headers=headers)
            resp = urllib2.urlopen(request)
            logging.debug("Response code: %d", resp.getcode())
            resp.close()

            return(True)

        except urllib2.HTTPError as e:
            logging.debug("Response code: %d", e.code)

            if e.code in self.kill_codes:
                self.disabled = True
                logging.exception('Posting has been disabled.'
                                  'See previous errors for details.')
            else:
                logging.exception(
                    'error posting payload to api ingest endpoint (%s): %s',
                    self.eventurl, e)

        except Exception as e:
            logging.exception(
                'error posting payload to api ingest endpoint (%s): %s',
                self.eventurl, e)


Instruction:
Write a Python 3 function that can
post a check to the Metricly API.

Response:
def post_check(self, check):
        """
            :param check: Check to post to Metricly
            :type check: object
        """

        if self.disabled is True:
            logging.error('Posting has been disabled. '
                          'See previous errors for details.')
            return(False)

        url = self.checkurl + '/' \
            + check.name + '/' \
            + check.elementId + '/' \
            + str(check.ttl)
        headers = {'User-Agent': self.agent}
        try:
            request = urllib2.Request(
                url, data='', headers=headers)
            resp = self._repeat_request(request, self.connection_timeout)
            logging.debug("Response code: %d", resp.getcode())
            resp.close()

            return(True)

        except urllib2.HTTPError as e:
            logging.debug("Response code: %d", e.code)

            if e.code in self.kill_codes:
                self.disabled = True
                logging.exception('Posting has been disabled.'
                                  'See previous errors for details.')
            else:
                logging.exception(
                    'HTTPError posting payload to api ingest endpoint'
                    + ' (%s): %s',
                    url, e)


Instruction:
Make a summary of the following Python 3 code
def urlsplit(url):
    p = '((?P<scheme>.*)?.*://)?(?P<host>[^:/ ]+).?(?P<port>[0-9]*).*'
    m = re.search(p, url)
    scheme = m.group('scheme')
    host = m.group('host')
    port = m.group('port')

    _scheme, _netloc, path, query, _fragment = tuple(py_urlsplit(url))

    return scheme, host, port, path, query

Response: Split url into scheme host port path query fragment


Instruction:
How would you code a function in Python 3 to
generate URI from parameters.

Response:
def generate_url(scheme=None, host=None, port=None, path=None, query=None):
    """
    Generate URI from parameters.

    :param str scheme:
    :param str host:
    :param int port:
    :param str path:
    :param dict query:
    :return:
    """
    url = ""
    if scheme is not None:
        url += "%s://" % scheme
    if host is not None:
        url += host
    if port is not None:
        url += ":%s" % str(port)
    if path is not None:
        url += ensure_url_path_starts_with_slash(path)
    if query is not None:
        url += "?%s" % (urlencode(query))
    return url


Instruction:
Write a Python 3 function that can
download a file from the given url to the given directory.

Response:
def download(self, output_dir, url, overwrite):
        """ Dowload file to /tmp """
        tmp = self.url2tmp(output_dir, url)
        if os.path.isfile(tmp) and not overwrite:
            logging.info("File {0} already exists. Skipping download.".format(tmp))
            return tmp
        f = open(tmp, 'wb')
        logging.info("Downloading {0}".format(url))
        res = requests.get(url, stream=True)
        if res.status_code != 200:
            # failed to download, cleanup and raise exception
            f.close()
            os.remove(tmp)
            error = "{0}\n\nFailed to download < {0} >".format(res.content, url)
            raise IOError(error)
        for block in res.iter_content(1024):
            f.write(block)
        f.close()
        return tmp


Instruction:
Write a Python 3 script for
extracting POI nodes from osm pbf extract

Response:
def extract(self, pbf, output):
        """ extract POI nodes from osm pbf extract """
        logging.info("Extracting POI nodes from {0} to {1}".format(pbf, output))
        with open(output, 'w') as f:
            # define callback for each node that is processed
            def nodes_callback(nodes):
                for node in nodes:
                    node_id, tags, coordinates = node
                    # if any tags have a matching key then write record
                    if any([t in tags for t in POI_TAGS]):
                        f.write(json.dumps(dict(tags=tags, coordinates=coordinates)))
                        f.write('\n')
            parser = OSMParser(concurrency=4, nodes_callback=nodes_callback)
            parser.parse(pbf)
        return output


Instruction:
Implement a Python 3 function for
converting url to tmp filename

Response:
def url2tmp(self, root, url):
        """ convert url path to filename """
        filename = url.rsplit('/', 1)[-1]
        return os.path.join(root, filename)


Instruction:
How would you code a function in Python 3 to
prompt the user with a default. Returns user input from stdin.

Response:
def ask_user(prompt: str, default: str = None) -> Optional[str]:
    """
    Prompts the user, with a default. Returns user input from ``stdin``.
    """
    if default is None:
        prompt += ": "
    else:
        prompt += " [" + default + "]: "
    result = input(prompt)
    return result if len(result) > 0 else default


Instruction:
How would you explain what the following Python 3 function does
def get_save_as_filename(defaultfilename: str,
                         defaultextension: str,
                         title: str = "Save As") -> str:
    """
    Provides a GUI "Save As" dialogue (via ``tkinter``) and returns the
    filename.
    """
    root = tkinter.Tk()  # create and get Tk topmost window
    # (don't do this too early; the command prompt loses focus)
    root.withdraw()  # won't need this; this gets rid of a blank Tk window
    root.attributes('-topmost', True)  # makes the tk window topmost
    filename = filedialog.asksaveasfilename(
        initialfile=defaultfilename,
        defaultextension=defaultextension,
        parent=root,
        title=title
    )
    root.attributes('-topmost', False)  # stop the tk window being topmost
    return filename

Response: Provides a GUI Save As dialogue and returns the filename.


Instruction:
How would you code a function in Python 3 to
provide a GUI Open dialogue and returns the filename.

Response:
def get_open_filename(defaultfilename: str,
                      defaultextension: str,
                      title: str = "Open") -> str:
    """
    Provides a GUI "Open" dialogue (via ``tkinter``) and returns the filename.
    """
    root = tkinter.Tk()  # create and get Tk topmost window
    # (don't do this too early; the command prompt loses focus)
    root.withdraw()  # won't need this; this gets rid of a blank Tk window
    root.attributes('-topmost', True)  # makes the tk window topmost
    filename = filedialog.askopenfilename(
        initialfile=defaultfilename,
        defaultextension=defaultextension,
        parent=root,
        title=title
    )
    root.attributes('-topmost', False)  # stop the tk window being topmost
    return filename


Instruction:
Explain what the following Python 3 code does
def str2bool(v: str) -> bool:
    lv = v.lower()
    if lv in ('yes', 'true', 't', 'y', '1'):
        return True
    elif lv in ('no', 'false', 'f', 'n', '0'):
        return False
    else:
        raise ArgumentTypeError('Boolean value expected.')

Response: Convert a string to a boolean value.


Instruction:
Write a Python 3 function that can
call to abort the request on timeout

Response:
def abort_request(self, request):
        """Called to abort request on timeout"""
        self.timedout = True
        try:
            request.cancel()
        except error.AlreadyCancelled:
            return


Instruction:
Create a Python 3 function to
make an HTTP request and return the body

Response:
def getBody(cls, url, method='GET', headers={}, data=None, socket=None, timeout=120):
        """Make an HTTP request and return the body
        """
        if not 'User-Agent' in headers:
            headers['User-Agent'] = ['Tensor HTTP checker']

        return cls().request(url, method, headers, data, socket, timeout)


Instruction:
How would you explain what the following Python 3 function does
def getJson(cls, url, method='GET', headers={}, data=None, socket=None, timeout=120):
        if not 'Content-Type' in headers:
            headers['Content-Type'] = ['application/json']

        body = yield cls().getBody(url, method, headers, data, socket, timeout)

        defer.returnValue(json.loads(body))

Response: Fetch a JSON result via HTTP HTTP


Instruction:
How would you code a function in Python 3 to
return the covariance matrix aligned to the fit.

Response:
def aligned_covariance(fit, type='noise'):
    """
    Covariance rescaled so that eigenvectors sum to 1
    and rotated into data coordinates from PCA space
    """
    cov = fit._covariance_matrix(type)
    # Rescale eigenvectors to sum to 1
    cov /= N.linalg.norm(cov)
    return dot(fit.axes,cov)


Instruction:
Write a Python 3 function for
finding the angle between the nominal vectors fit1 and fit2.

Response:
def fit_angle(fit1, fit2, degrees=True):
    """
    Finds the angle between the nominal vectors
    """
    return N.degrees(angle(fit1.normal,fit2.normal))


Instruction:
Write a Python 3 function that can
calculate the similarity between two fit objects.

Response:
def fit_similarity(fit1, fit2):
    """
    Distance apart for vectors, given in
    standard deviations
    """
    cov1 = aligned_covariance(fit1)
    cov2 = aligned_covariance(fit2)
    if fit2.axes[2,2] < 0:
        cov2 *= -1
    v0 = fit1.normal-fit2.normal
    cov0 = cov1+cov2 # Axes are aligned, so no covariances

    # Find distance of point from center

    # Decompose covariance matrix
    U,s,V = N.linalg.svd(cov0)
    rotated = dot(V,v0) # rotate vector into PCA space
    val = rotated**2/N.sqrt(s)
    return N.sqrt(val.sum())


Instruction:
Can you generate a brief explanation for the following Python 3 code
def axis_aligned_transforms():
    I = N.eye(3)
    xy = I[:2]
    xz = N.vstack((I[0],I[2]))
    yz = I[1:]
    return xy,xz,yz

Response: Generates three transformation matrices to map three - dimensional data on the xy xz and yz planes respectively.


Instruction:
Make a summary of the following Python 3 code
def png_img_html_from_pyplot_figure(fig: "Figure",
                                    dpi: int = 100,
                                    extra_html_class: str = None) -> str:
    """
    Converts a ``pyplot`` figure to an HTML IMG tag with encapsulated PNG.
    """
    if fig is None:
        return ""
    # Make a file-like object
    memfile = io.BytesIO()
    # In general, can do
    #   fig.savefig(filename/file-like-object/backend, format=...)
    # or
    #   backend.savefig(fig):
    # see e.g. http://matplotlib.org/api/backend_pdf_api.html
    fig.savefig(memfile, format="png", dpi=dpi)
    memfile.seek(0)
    pngblob = memoryview(memfile.read())
    return rnc_web.get_png_img_html(pngblob, extra_html_class)

Response: Converts a pyplot figure to an HTML IMG tag with encapsulated PNG.


Instruction:
Can you implement a function in Python 3 that
converts a pyplot figure to an SVG tag.

Response:
def svg_html_from_pyplot_figure(fig: "Figure") -> str:
    """
    Converts a ``pyplot`` figure to an SVG tag.
    """
    if fig is None:
        return ""
    memfile = io.BytesIO()  # StringIO doesn't like mixing str/unicode
    fig.savefig(memfile, format="svg")
    return memfile.getvalue().decode("utf-8")


Instruction:
Create a Python 3 function to
set the current font size within the matplotlib library.

Response:
def set_matplotlib_fontsize(matplotlib: ModuleType,
                            fontsize: Union[int, float] = 12) -> None:
    """
    Sets the current font size within the ``matplotlib`` library.

    **WARNING:** not an appropriate method for multithreaded environments, as
    it writes (indirectly) to ``matplotlib`` global objects. See CamCOPS for
    alternative methods.
    """
    font = {
        # http://stackoverflow.com/questions/3899980
        # http://matplotlib.org/users/customizing.html
        'family': 'sans-serif',
        # ... serif, sans-serif, cursive, fantasy, monospace
        'style': 'normal',  # normal (roman), italic, oblique
        'variant': 'normal',  # normal, small-caps
        'weight': 'normal',
        # ... normal [=400], bold [=700], bolder [relative to current],
        # lighter [relative], 100, 200, 300, ..., 900
        'size': fontsize  # in pt (default 12)
    }
    # noinspection PyUnresolvedReferences
    matplotlib.rc('font', **font)
    legend = {
        # http://stackoverflow.com/questions/7125009
        'fontsize': fontsize
    }
    # noinspection PyUnresolvedReferences
    matplotlib.rc('legend', **legend)


Instruction:
Explain what the following Python 3 code does
def massage_keys(keys):
    m_keys = []
    for key in keys:
        if key.startswith('keybase:'):
            m_keys.append(cryptorito.key_from_keybase(key[8:])['fingerprint'])
        else:
            m_keys.append(key)

    return m_keys

Response: Takes a list of GPG keys and returns a list of GPG keys.


Instruction:
Can you tell what is the following Python 3 function doing
def encrypt_file(src, dest, csv_keys):
    keys = massage_keys(csv_keys.split(','))
    cryptorito.encrypt(src, dest, keys)

Response:
Encrypt a file with the specific GPG keys and write out
    to the specified path


Instruction:
Write a Python 3 script for
encrypting what comes in from stdin and return base64 encrypted against the specified keys returning on stdout

Response:
def encrypt_var(csv_keys):
    """Encrypt what comes in from stdin and return base64
    encrypted against the specified keys, returning on stdout"""
    keys = massage_keys(csv_keys.split(','))
    data = sys.stdin.read()
    encrypted = cryptorito.encrypt_var(data, keys)
    print(cryptorito.portable_b64encode(encrypted))


Instruction:
Write a Python 3 script for
importing a public GPG key from Keybase

Response:
def import_keybase(useropt):
    """Imports a public GPG key from Keybase"""
    public_key = None
    u_bits = useropt.split(':')
    username = u_bits[0]
    if len(u_bits) == 1:
        public_key = cryptorito.key_from_keybase(username)
    else:
        fingerprint = u_bits[1]
        public_key = cryptorito.key_from_keybase(username, fingerprint)

    if cryptorito.has_gpg_key(public_key['fingerprint']):
        sys.exit(2)

    cryptorito.import_gpg_key(public_key['bundle'].encode('ascii'))
    sys.exit(0)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def do_thing():
    if len(sys.argv) == 5 and sys.argv[1] == "encrypt_file":
        encrypt_file(sys.argv[2], sys.argv[3], sys.argv[4])
    elif len(sys.argv) == 4 and sys.argv[1] == "decrypt_file":
        decrypt_file(sys.argv[2], sys.argv[3])
    elif len(sys.argv) == 3 and sys.argv[1] == "encrypt":
        encrypt_var(sys.argv[2])
    elif len(sys.argv) == 2 and sys.argv[1] == "decrypt":
        decrypt_var()
    elif len(sys.argv) == 3 and sys.argv[1] == "decrypt":
        decrypt_var(passphrase=sys.argv[2])
    elif len(sys.argv) == 3 and sys.argv[1] == "has_key":
        has_key(sys.argv[2])
    elif len(sys.argv) == 3 and sys.argv[1] == "import_keybase":
        import_keybase(sys.argv[2])
    elif len(sys.argv) == 3 and sys.argv[1] == "export":
        export_key(sys.argv[2])
    else:
        print("Cryptorito testing wrapper. Not suitable for routine use.",
              file=sys.stderr)
        sys.exit(1)

Response: Execute command line cryptorito actions


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_monochrome_handler(
        extranames: List[str] = None,
        with_process_id: bool = False,
        with_thread_id: bool = False,
        stream: TextIO = None) -> logging.StreamHandler:
    """
    Gets a monochrome log handler using a standard format.

    Args:
        extranames: additional names to append to the logger's name
        with_process_id: include the process ID in the logger's name?
        with_thread_id: include the thread ID in the logger's name?
        stream: ``TextIO`` stream to send log output to

    Returns:
        the :class:`logging.StreamHandler`

    """
    fmt = "%(asctime)s.%(msecs)03d"
    if with_process_id or with_thread_id:
        procinfo = []  # type: List[str]
        if with_process_id:
            procinfo.append("p%(process)d")
        if with_thread_id:
            procinfo.append("t%(thread)d")
        fmt += " [{}]".format(".".join(procinfo))
    extras = ":" + ":".join(extranames) if extranames else ""
    fmt += " %(name)s{extras}:%(levelname)s: ".format(extras=extras)
    fmt += "%(message)s"
    f = logging.Formatter(fmt, datefmt=LOG_DATEFMT, style='%')
    h = logging.StreamHandler(stream)
    h.setFormatter(f)
    return h

Response: Returns a Monochrome log handler using a standard format.


Instruction:
How would you code a function in Python 3 to
return a colour log handler using a standard format.

Response:
def get_colour_handler(extranames: List[str] = None,
                       with_process_id: bool = False,
                       with_thread_id: bool = False,
                       stream: TextIO = None) -> logging.StreamHandler:
    """
    Gets a colour log handler using a standard format.

    Args:
        extranames: additional names to append to the logger's name
        with_process_id: include the process ID in the logger's name?
        with_thread_id: include the thread ID in the logger's name?
        stream: ``TextIO`` stream to send log output to

    Returns:
        the :class:`logging.StreamHandler`

    """
    fmt = "%(white)s%(asctime)s.%(msecs)03d"  # this is dim white = grey
    if with_process_id or with_thread_id:
        procinfo = []  # type: List[str]
        if with_process_id:
            procinfo.append("p%(process)d")
        if with_thread_id:
            procinfo.append("t%(thread)d")
        fmt += " [{}]".format(".".join(procinfo))
    extras = ":" + ":".join(extranames) if extranames else ""
    fmt += " %(name)s{extras}:%(levelname)s: ".format(extras=extras)
    fmt += "%(reset)s%(log_color)s%(message)s"
    cf = ColoredFormatter(fmt,
                          datefmt=LOG_DATEFMT,
                          reset=True,
                          log_colors=LOG_COLORS,
                          secondary_log_colors={},
                          style='%')
    ch = logging.StreamHandler(stream)
    ch.setFormatter(cf)
    return ch


Instruction:
Implement a function in Python 3 to
configure a logger for a colour.

Response:
def configure_logger_for_colour(logger: logging.Logger,
                                level: int = logging.INFO,
                                remove_existing: bool = False,
                                extranames: List[str] = None,
                                with_process_id: bool = False,
                                with_thread_id: bool = False) -> None:
    """
    Applies a preconfigured datetime/colour scheme to a logger.

    Should ONLY be called from the ``if __name__ == 'main'`` script;
    see https://docs.python.org/3.4/howto/logging.html#library-config.

    Args:
        logger: logger to modify
        level: log level to set
        remove_existing: remove existing handlers from logger first?
        extranames: additional names to append to the logger's name
        with_process_id: include the process ID in the logger's name?
        with_thread_id: include the thread ID in the logger's name?
    """
    if remove_existing:
        logger.handlers = []  # http://stackoverflow.com/questions/7484454
    handler = get_colour_handler(extranames,
                                 with_process_id=with_process_id,
                                 with_thread_id=with_thread_id)
    handler.setLevel(level)
    logger.addHandler(handler)
    logger.setLevel(level)


Instruction:
Can you generate the documentation for the following Python 3 function
def main_only_quicksetup_rootlogger(level: int = logging.DEBUG,
                                    with_process_id: bool = False,
                                    with_thread_id: bool = False) -> None:
    """
    Quick function to set up the root logger for colour.

    Should ONLY be called from the ``if __name__ == 'main'`` script;
    see https://docs.python.org/3.4/howto/logging.html#library-config.

    Args:
        level: log level to set
        with_process_id: include the process ID in the logger's name?
        with_thread_id: include the thread ID in the logger's name?
    """
    # Nasty. Only call from "if __name__ == '__main__'" clauses!
    rootlogger = logging.getLogger()
    configure_logger_for_colour(rootlogger, level, remove_existing=True,
                                with_process_id=with_process_id,
                                with_thread_id=with_thread_id)

Response: Quick function to set up the root logger for colour.


Instruction:
Make a summary of the following Python 3 code
def remove_all_logger_handlers(logger: logging.Logger) -> None:
    while logger.handlers:
        h = logger.handlers[0]
        logger.removeHandler(h)

Response: Removes all handlers from a logger.


Instruction:
Write a Python 3 function for
resetting the log format of the given logger.

Response:
def reset_logformat(logger: logging.Logger,
                    fmt: str,
                    datefmt: str = '%Y-%m-%d %H:%M:%S') -> None:
    """
    Create a new formatter and apply it to the logger.

    :func:`logging.basicConfig` won't reset the formatter if another module
    has called it, so always set the formatter like this.

    Args:
        logger: logger to modify
        fmt: passed to the ``fmt=`` argument of :class:`logging.Formatter`
        datefmt: passed to the ``datefmt=`` argument of
            :class:`logging.Formatter`
    """
    handler = logging.StreamHandler()
    formatter = logging.Formatter(fmt=fmt, datefmt=datefmt)
    handler.setFormatter(formatter)
    remove_all_logger_handlers(logger)
    logger.addHandler(handler)
    logger.propagate = False


Instruction:
Make a summary of the following Python 3 code
def reset_logformat_timestamped(logger: logging.Logger,
                                extraname: str = "",
                                level: int = logging.INFO) -> None:
    """
    Apply a simple time-stamped log format to an existing logger, and set
    its loglevel to either ``logging.DEBUG`` or ``logging.INFO``.

    Args:
        logger: logger to modify
        extraname: additional name to append to the logger's name
        level: log level to set
    """
    namebit = extraname + ":" if extraname else ""
    fmt = ("%(asctime)s.%(msecs)03d:%(levelname)s:%(name)s:" + namebit +
           "%(message)s")
    # logger.info(fmt)
    reset_logformat(logger, fmt=fmt)
    # logger.info(fmt)
    logger.setLevel(level)

Response: Reset a logger s logformat to a simple time - stamped log format.


Instruction:
Write a Python 3 script to
apply a preconfigured datetime / colour scheme to ALL loggers.

Response:
def configure_all_loggers_for_colour(remove_existing: bool = True) -> None:
    """
    Applies a preconfigured datetime/colour scheme to ALL logger.

    Should ONLY be called from the ``if __name__ == 'main'`` script;
    see https://docs.python.org/3.4/howto/logging.html#library-config.

    Generally MORE SENSIBLE just to apply a handler to the root logger.

    Args:
        remove_existing: remove existing handlers from logger first?

    """
    handler = get_colour_handler()
    apply_handler_to_all_logs(handler, remove_existing=remove_existing)


Instruction:
How would you implement a function in Python 3 that
applies a handler to all logs in the root logger.

Response:
def apply_handler_to_root_log(handler: logging.Handler,
                              remove_existing: bool = False) -> None:
    """
    Applies a handler to all logs, optionally removing existing handlers.

    Should ONLY be called from the ``if __name__ == 'main'`` script;
    see https://docs.python.org/3.4/howto/logging.html#library-config.

    Generally MORE SENSIBLE just to apply a handler to the root logger.

    Args:
        handler: the handler to apply
        remove_existing: remove existing handlers from logger first?
    """
    rootlog = logging.getLogger()
    if remove_existing:
        rootlog.handlers = []
    rootlog.addHandler(handler)


Instruction:
Create a Python 3 function for
applying a handler to all logs.

Response:
def apply_handler_to_all_logs(handler: logging.Handler,
                              remove_existing: bool = False) -> None:
    """
    Applies a handler to all logs, optionally removing existing handlers.

    Should ONLY be called from the ``if __name__ == 'main'`` script;
    see https://docs.python.org/3.4/howto/logging.html#library-config.

    Generally MORE SENSIBLE just to apply a handler to the root logger.

    Args:
        handler: the handler to apply
        remove_existing: remove existing handlers from logger first?
    """
    # noinspection PyUnresolvedReferences
    for name, obj in logging.Logger.manager.loggerDict.items():
        if remove_existing:
            obj.handlers = []  # http://stackoverflow.com/questions/7484454
        obj.addHandler(handler)


Instruction:
Create a Python 3 function for
copying all currently configured logs to a file.

Response:
def copy_root_log_to_file(filename: str,
                          fmt: str = LOG_FORMAT,
                          datefmt: str = LOG_DATEFMT) -> None:
    """
    Copy all currently configured logs to the specified file.

    Should ONLY be called from the ``if __name__ == 'main'`` script;
    see https://docs.python.org/3.4/howto/logging.html#library-config.
    """
    fh = logging.FileHandler(filename)
    # default file mode is 'a' for append
    formatter = logging.Formatter(fmt=fmt, datefmt=datefmt)
    fh.setFormatter(formatter)
    apply_handler_to_root_log(fh)


Instruction:
How would you code a function in Python 3 to
copy all currently configured logs to a file.

Response:
def copy_all_logs_to_file(filename: str,
                          fmt: str = LOG_FORMAT,
                          datefmt: str = LOG_DATEFMT) -> None:
    """
    Copy all currently configured logs to the specified file.

    Should ONLY be called from the ``if __name__ == 'main'`` script;
    see https://docs.python.org/3.4/howto/logging.html#library-config.

    Args:
        filename: file to send log output to
        fmt: passed to the ``fmt=`` argument of :class:`logging.Formatter`
        datefmt: passed to the ``datefmt=`` argument of
            :class:`logging.Formatter`
    """
    fh = logging.FileHandler(filename)
    # default file mode is 'a' for append
    formatter = logging.Formatter(fmt=fmt, datefmt=datefmt)
    fh.setFormatter(formatter)
    apply_handler_to_all_logs(fh)


Instruction:
Implement a Python 3 function for
returning information on a log formatter as a dictionary.

Response:
def get_formatter_report(f: logging.Formatter) -> Optional[Dict[str, str]]:
    """
    Returns information on a log formatter, as a dictionary.
    For debugging.
    """
    if f is None:
        return None
    return {
        '_fmt': f._fmt,
        'datefmt': f.datefmt,
        '_style': str(f._style),
    }


Instruction:
Create a Python 3 function for
returning information on a log handler as a dictionary.

Response:
def get_handler_report(h: logging.Handler) -> Dict[str, Any]:
    """
    Returns information on a log handler, as a dictionary.
    For debugging.
    """
    return {
        'get_name()': h.get_name(),
        'level': h.level,
        'formatter': get_formatter_report(h.formatter),
        'filters': h.filters,
    }


Instruction:
Write a Python 3 script to
return information on a log as a dictionary. For debugging.

Response:
def get_log_report(log: Union[logging.Logger,
                              logging.PlaceHolder]) -> Dict[str, Any]:
    """
    Returns information on a log, as a dictionary. For debugging.
    """
    if isinstance(log, logging.Logger):
        # suppress invalid error for Logger.manager:
        # noinspection PyUnresolvedReferences
        return {
            '(object)': str(log),
            'level': log.level,
            'disabled': log.disabled,
            'propagate': log.propagate,
            'parent': str(log.parent),
            'manager': str(log.manager),
            'handlers': [get_handler_report(h) for h in log.handlers],
        }
    elif isinstance(log, logging.PlaceHolder):
        return {
            "(object)": str(log),
        }
    else:
        raise ValueError("Unknown object type: {!r}".format(log))


Instruction:
Here you have a function in Python 3, explain what it does
def print_report_on_all_logs() -> None:
    d = {}
    # noinspection PyUnresolvedReferences
    for name, obj in logging.Logger.manager.loggerDict.items():
        d[name] = get_log_report(obj)
    rootlogger = logging.getLogger()
    d['(root logger)'] = get_log_report(rootlogger)
    print(json.dumps(d, sort_keys=True, indent=4, separators=(',', ': ')))

Response: Use this function to print a report on all logs.