Instruction:
Create a Python 3 function to
add a new url rule for static files.

Response:
def add_static_url(self, url_path, directory, endpoint=None, roles=None):
        """Add a new url rule for static files.

        :param url_path: subpath from application static url path. No heading
            or trailing slash.
        :param directory: directory to serve content from.
        :param endpoint: flask endpoint name for this url rule.

        Example::

           app.add_static_url('myplugin',
                              '/path/to/myplugin/resources',
                              endpoint='myplugin_static')

        With default setup it will serve content from directory
        `/path/to/myplugin/resources` from url `http://.../static/myplugin`
        """
        url_path = self.static_url_path + "/" + url_path + "/<path:filename>"
        self.add_url_rule(
            url_path,
            endpoint=endpoint,
            view_func=partial(send_file_from_directory, directory=directory),
            roles=roles,
        )
        self.add_access_controller(
            endpoint, allow_access_for_roles(Anonymous), endpoint=True
        )


Instruction:
Explain what the following Python 3 code does
def _message_send(self, connection):
    sender = current_app.config["MAIL_SENDER"]
    if not self.extra_headers:
        self.extra_headers = {}
    self.extra_headers["Sender"] = sender
    connection.send(self, sender)

Response: Send a single message instance.


Instruction:
Here you have a function in Python 3, explain what it does
def _filter_metadata_for_connection(target, connection, **kw):
    engine = connection.engine.name
    default_engines = (engine,)
    tables = target if isinstance(target, sa.Table) else kw.get("tables", [])
    for table in tables:
        indexes = list(table.indexes)
        for idx in indexes:
            if engine not in idx.info.get("engines", default_engines):
                table.indexes.remove(idx)

Response: Filter the metadata for a connection.


Instruction:
Explain what the following Python 3 code does
def url_for(obj, **kw):
    if isinstance(obj, str):
        return flask_url_for(obj, **kw)

    try:
        return current_app.default_view.url_for(obj, **kw)
    except KeyError:
        if hasattr(obj, "_url"):
            return obj._url
        elif hasattr(obj, "url"):
            return obj.url

    raise BuildError(repr(obj), kw, "GET")

Response: Polymorphic variant of Flask s url_for function.


Instruction:
Make a summary of the following Python 3 code
def send_file_from_directory(filename, directory, app=None):
    if app is None:
        app = current_app
    cache_timeout = app.get_send_file_max_age(filename)
    return send_from_directory(directory, filename, cache_timeout=cache_timeout)

Response: Send a file from a directory.


Instruction:
Implement a Python 3 function for
getting models modified at the given date with the Audit service.

Response:
def get_model_changes(
    entity_type, year=None, month=None, day=None, hour=None, since=None
):
    # type: (Text, int, int, int, int, datetime) -> Query
    """Get models modified at the given date with the Audit service.

    :param entity_type: string like "extranet_medicen.apps.crm.models.Compte".
      Beware the typo, there won't be a warning message.
    :param since: datetime
    :param year: int
    :param month: int
    :param day: int
    :param hour: int

    :returns: a query object
    """
    query = AuditEntry.query

    if since:
        query = query.filter(AuditEntry.happened_at >= since)

    if year:
        query = query.filter(extract("year", AuditEntry.happened_at) == year)
    if month:
        query = query.filter(extract("month", AuditEntry.happened_at) == month)
    if day:
        query = query.filter(extract("day", AuditEntry.happened_at) == day)
    if hour:
        query = query.filter(extract("hour", AuditEntry.happened_at) == hour)

    query = query.filter(AuditEntry.entity_type.like(entity_type)).order_by(
        AuditEntry.happened_at
    )

    return query


Instruction:
Write a Python 3 function for
adding the changed columns as a diff attribute.

Response:
def get_columns_diff(changes):
    """Add the changed columns as a diff attribute.

    - changes: a list of changes (get_model_changes query.all())

    Return: the same list, to which elements we added a "diff"
    attribute containing the changed columns. Diff defaults to [].
    """
    for change in changes:
        change.diff = []
        elt_changes = change.get_changes()
        if elt_changes:
            change.diff = elt_changes.columns

    return changes


Instruction:
Explain what the following Python 3 code does
def _has_argument(func):
    if hasattr(inspect, 'signature'):
        # New way in python 3.3
        sig = inspect.signature(func)
        return bool(sig.parameters)
    else:
        # Old way
        return bool(inspect.getargspec(func).args)

Response: Test whether a function expects an argument.


Instruction:
How would you code a function in Python 3 to
create a new Site object.

Response:
def make_site(cls,
                  searchpath="templates",
                  outpath=".",
                  contexts=None,
                  rules=None,
                  encoding="utf8",
                  followlinks=True,
                  extensions=None,
                  staticpaths=None,
                  filters=None,
                  env_globals=None,
                  env_kwargs=None,
                  mergecontexts=False):
        """Create a :class:`Site <Site>` object.

        :param searchpath:
            A string representing the absolute path to the directory that the
            Site should search to discover templates. Defaults to
            ``'templates'``.

            If a relative path is provided, it will be coerced to an absolute
            path by prepending the directory name of the calling module. For
            example, if you invoke staticjinja using ``python build.py`` in
            directory ``/foo``, then *searchpath* will be ``/foo/templates``.

        :param outpath:
            A string representing the name of the directory that the Site
            should store rendered files in. Defaults to ``'.'``.

        :param contexts:
            A list of *(regex, context)* pairs. The Site will render templates
            whose name match *regex* using *context*. *context* must be either
            a dictionary-like object or a function that takes either no
            arguments or a single :class:`jinja2.Template` as an argument and
            returns a dictionary representing the context. Defaults to ``[]``.

        :param rules:
            A list of *(regex, function)* pairs. The Site will delegate
            rendering to *function* if *regex* matches the name of a template
            during rendering. *function* must take a
            :class:`jinja2.Environment` object, a filename, and a context as
            parameters and render the template. Defaults to ``[]``.

        :param encoding:
            A string representing the encoding that the Site should use when
            rendering templates. Defaults to ``'utf8'``.

        :param followlinks:
            A boolean describing whether symlinks in searchpath should be
            followed or not. Defaults to ``True``.

        :param extensions:
            A list of :ref:`Jinja extensions <jinja-extensions>` that the
            :class:`jinja2.Environment` should use. Defaults to ``[]``.

        :param staticpaths:
            List of directories to get static files from (relative to
            searchpath).  Defaults to ``None``.

        :param filters:
            A dictionary of Jinja2 filters to add to the Environment.  Defaults
            to ``{}``.

        :param env_globals:
            A mapping from variable names that should be available all the time
            to their values. Defaults to ``{}``.

        :param env_kwargs:
            A dictionary that will be passed as keyword arguments to the
            jinja2 Environment. Defaults to ``{}``.

        :param mergecontexts:
            A boolean value. If set to ``True``, then all matching regex from
            the contexts list will be merged (in order) to get the final
            context.  Otherwise, only the first matching regex is used.
            Defaults to ``False``.
        """
        # Coerce search to an absolute path if it is not already
        if not os.path.isabs(searchpath):
            # TODO: Determine if there is a better way to write do this
            calling_module = inspect.getmodule(inspect.stack()[-1][0])
            # Absolute path to project
            project_path = os.path.realpath(os.path.dirname(
                calling_module.__file__))
            searchpath = os.path.join(project_path, searchpath)

        if env_kwargs is None:
            env_kwargs = {}
        env_kwargs['loader'] = FileSystemLoader(searchpath=searchpath,
                                                encoding=encoding,
                                                followlinks=followlinks)
        env_kwargs.setdefault('extensions', extensions or [])
        environment = Environment(**env_kwargs)
        if filters:
            environment.filters.update(filters)

        if env_globals:
            environment.globals.update(env_globals)

        logger = logging.getLogger(__name__)
        logger.setLevel(logging.INFO)
        logger.addHandler(logging.StreamHandler())
        return cls(environment,
                   searchpath=searchpath,
                   outpath=outpath,
                   encoding=encoding,
                   logger=logger,
                   rules=rules,
                   contexts=contexts,
                   staticpaths=staticpaths,
                   mergecontexts=mergecontexts,
                   )


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_context(self, template):
        context = {}
        for regex, context_generator in self.contexts:
            if re.match(regex, template.name):
                if inspect.isfunction(context_generator):
                    if _has_argument(context_generator):
                        context.update(context_generator(template))
                    else:
                        context.update(context_generator())
                else:
                    context.update(context_generator)

                if not self.mergecontexts:
                    break
        return context

Response: Get the context for a template.


Instruction:
Can you tell what is the following Python 3 function doing
def get_rule(self, template_name):
        for regex, render_func in self.rules:
            if re.match(regex, template_name):
                return render_func
        raise ValueError("no matching rule")

Response: Find a matching compilation rule for a template name.


Instruction:
How would you code a function in Python 3 to
check if a file is static.

Response:
def is_static(self, filename):
        """Check if a file is a static file (which should be copied, rather
        than compiled using Jinja2).

        A file is considered static if it lives in any of the directories
        specified in ``staticpaths``.

        :param filename: the name of the file to check

        """
        if self.staticpaths is None:
            # We're not using static file support
            return False

        for path in self.staticpaths:
            if filename.startswith(path):
                return True
        return False


Instruction:
How would you code a function in Python 3 to
check if a file is a partial.

Response:
def is_partial(self, filename):
        """Check if a file is a partial.

        Partial files are not rendered, but they are used in rendering
        templates.

        A file is considered a partial if it or any of its parent directories
        are prefixed with an ``'_'``.

        :param filename: the name of the file to check
        """
        return any((x.startswith("_") for x in filename.split(os.path.sep)))


Instruction:
How would you explain what the following Python 3 function does
def is_template(self, filename):
        if self.is_partial(filename):
            return False

        if self.is_ignored(filename):
            return False

        if self.is_static(filename):
            return False

        return True

Response: Check if a file is a template.


Instruction:
Create a Python 3 function to
ensure the output directory for a template exists.

Response:
def _ensure_dir(self, template_name):
        """Ensure the output directory for a template exists."""
        head = os.path.dirname(template_name)
        if head:
            file_dirpath = os.path.join(self.outpath, head)
            if not os.path.exists(file_dirpath):
                os.makedirs(file_dirpath)


Instruction:
How would you code a function in Python 3 to
render a single template object.

Response:
def render_template(self, template, context=None, filepath=None):
        """Render a single :class:`jinja2.Template` object.

        If a Rule matching the template is found, the rendering task is
        delegated to the rule.

        :param template:
            A :class:`jinja2.Template` to render.

        :param context:
            Optional. A dictionary representing the context to render
            *template* with. If no context is provided, :meth:`get_context` is
            used to provide a context.

        :param filepath:
            Optional. A file or file-like object to dump the complete template
            stream into. Defaults to to ``os.path.join(self.outpath,
            template.name)``.

        """
        self.logger.info("Rendering %s..." % template.name)

        if context is None:
            context = self.get_context(template)

        if not os.path.exists(self.outpath):
            os.makedirs(self.outpath)
        self._ensure_dir(template.name)

        try:
            rule = self.get_rule(template.name)
        except ValueError:
            if filepath is None:
                filepath = os.path.join(self.outpath, template.name)
            template.stream(**context).dump(filepath, self.encoding)
        else:
            rule(self, template, **context)


Instruction:
How would you explain what the following Python 3 function does
def render_templates(self, templates, filepath=None):
        for template in templates:
            self.render_template(template, filepath)

Response: Render a collection of templates into a file or file - like object.


Instruction:
Implement a Python 3 function for
returning a list of files that depend on the file named filename.

Response:
def get_dependencies(self, filename):
        """Get a list of files that depends on the file named *filename*.

        :param filename: the name of the file to find dependencies of
        """
        if self.is_partial(filename):
            return self.templates
        elif self.is_template(filename):
            return [self.get_template(filename)]
        elif self.is_static(filename):
            return [filename]
        else:
            return []


Instruction:
Implement a Python 3 function for
generating the site. :param use_reloader: if given, reload templates on modification

Response:
def render(self, use_reloader=False):
        """Generate the site.

        :param use_reloader: if given, reload templates on modification
        """
        self.render_templates(self.templates)
        self.copy_static(self.static_names)

        if use_reloader:
            self.logger.info("Watching '%s' for changes..." %
                             self.searchpath)
            self.logger.info("Press Ctrl+C to stop.")
            Reloader(self).watch()


Instruction:
Can you create a Python 3 function that
registers one or many jinja2. Loader instances for templates lookup.

Response:
def register_jinja_loaders(self, *loaders):
        """Register one or many `jinja2.Loader` instances for templates lookup.

        During application initialization plugins can register a loader so that
        their templates are available to jinja2 renderer.

        Order of registration matters: last registered is first looked up (after
        standard Flask lookup in app template folder). This allows a plugin to
        override templates provided by others, or by base application. The
        application can override any template from any plugins from its template
        folder (See `Flask.Application.template_folder`).

        :raise: `ValueError` if a template has already been rendered
        """
        if not hasattr(self, "_jinja_loaders"):
            raise ValueError(
                "Cannot register new jinja loaders after first template rendered"
            )

        self._jinja_loaders.extend(loaders)


Instruction:
Can you tell what is the following Python 3 function doing
def jinja_loader(self):
        loaders = self._jinja_loaders
        del self._jinja_loaders
        loaders.append(Flask.jinja_loader.func(self))
        loaders.reverse()
        return jinja2.ChoiceLoader(loaders)

Response:
Search templates in custom app templates dir ( default Flask
        behaviour fallback on abilian templates.


Instruction:
Explain what the following Python 3 code does
def render(args):
    srcpath = (
        os.path.join(os.getcwd(), 'templates') if args['--srcpath'] is None
        else args['--srcpath'] if os.path.isabs(args['--srcpath'])
        else os.path.join(os.getcwd(), args['--srcpath'])
    )

    if not os.path.isdir(srcpath):
        print("The templates directory '%s' is invalid."
              % srcpath)
        sys.exit(1)

    if args['--outpath'] is not None:
        outpath = args['--outpath']
    else:
        outpath = os.getcwd()

    if not os.path.isdir(outpath):
        print("The output directory '%s' is invalid."
              % outpath)
        sys.exit(1)

    staticdirs = args['--static']
    staticpaths = None

    if staticdirs:
        staticpaths = staticdirs.split(",")
        for path in staticpaths:
            path = os.path.join(srcpath, path)
            if not os.path.isdir(path):
                print("The static files directory '%s' is invalid." % path)
                sys.exit(1)

    site = staticjinja.make_site(
        searchpath=srcpath,
        outpath=outpath,
        staticpaths=staticpaths
    )

    use_reloader = args['watch']

    site.render(use_reloader=use_reloader)

Response: Render a single site.


Instruction:
How would you implement a function in Python 3 that
returns a string suitable for query against allowed_roles_and_users or allowed_users_and_users field.

Response:
def indexable_role(principal):
    """Return a string suitable for query against `allowed_roles_and_users`
    field.

    :param principal: It can be :data:`Anonymous`, :data:`Authenticated`,
      or an instance of :class:`User` or :class:`Group`.
    """
    principal = unwrap(principal)

    if hasattr(principal, "is_anonymous") and principal.is_anonymous:
        # transform anonymous user to anonymous role
        principal = Anonymous

    if isinstance(principal, Role):
        return f"role:{principal.name}"
    elif isinstance(principal, User):
        fmt = "user:{:d}"
    elif isinstance(principal, Group):
        fmt = "group:{:d}"
    else:
        raise ValueError(repr(principal))

    return fmt.format(principal.id)


Instruction:
Write a Python 3 script for
converting a file to plain text.

Response:
def to_text(self, digest, blob, mime_type):
        """Convert a file to plain text.

        Useful for full-text indexing. Returns a Unicode string.
        """
        # Special case, for now (XXX).
        if mime_type.startswith("image/"):
            return ""

        cache_key = "txt:" + digest

        text = self.cache.get(cache_key)
        if text:
            return text

        # Direct conversion possible
        for handler in self.handlers:
            if handler.accept(mime_type, "text/plain"):
                text = handler.convert(blob)
                self.cache[cache_key] = text
                return text

        # Use PDF as a pivot format
        pdf = self.to_pdf(digest, blob, mime_type)
        for handler in self.handlers:
            if handler.accept("application/pdf", "text/plain"):
                text = handler.convert(pdf)
                self.cache[cache_key] = text
                return text

        raise HandlerNotFound(f"No handler found to convert from {mime_type} to text")


Instruction:
How would you code a function in Python 3 to
tell if there is a preview image.

Response:
def has_image(self, digest, mime_type, index, size=500):
        """Tell if there is a preview image."""
        cache_key = f"img:{index}:{size}:{digest}"
        return mime_type.startswith("image/") or cache_key in self.cache


Instruction:
Create a Python 3 function to
return an image for the given content in the image cache.

Response:
def get_image(self, digest, blob, mime_type, index, size=500):
        """Return an image for the given content, only if it already exists in
        the image cache."""
        # Special case, for now (XXX).
        if mime_type.startswith("image/"):
            return ""

        cache_key = f"img:{index}:{size}:{digest}"
        return self.cache.get(cache_key)


Instruction:
Can you generate the documentation for the following Python 3 function
def to_image(self, digest, blob, mime_type, index, size=500):
        # Special case, for now (XXX).
        if mime_type.startswith("image/"):
            return ""

        cache_key = f"img:{index}:{size}:{digest}"
        converted = self.cache.get(cache_key)
        if converted:
            return converted

        # Direct conversion possible
        for handler in self.handlers:
            if handler.accept(mime_type, "image/jpeg"):
                converted_images = handler.convert(blob, size=size)
                for i in range(0, len(converted_images)):
                    converted = converted_images[i]
                    cache_key = f"img:{i}:{size}:{digest}"
                    self.cache[cache_key] = converted
                return converted_images[index]

        # Use PDF as a pivot format
        pdf = self.to_pdf(digest, blob, mime_type)
        for handler in self.handlers:
            if handler.accept("application/pdf", "image/jpeg"):
                converted_images = handler.convert(pdf, size=size)
                for i in range(0, len(converted_images)):
                    converted = converted_images[i]
                    cache_key = f"img:{i}:{size}:{digest}"
                    self.cache[cache_key] = converted
                return converted_images[index]

        raise HandlerNotFound(f"No handler found to convert from {mime_type} to image")

Response: Convert a file to a list of images.


Instruction:
Can you implement a function in Python 3 that
gets a dictionary representing the metadata embedded in the given content.

Response:
def get_metadata(self, digest, content, mime_type):
        """Get a dictionary representing the metadata embedded in the given
        content."""

        # XXX: ad-hoc for now, refactor later
        if mime_type.startswith("image/"):
            img = Image.open(BytesIO(content))
            ret = {}
            if not hasattr(img, "_getexif"):
                return {}
            info = img._getexif()
            if not info:
                return {}
            for tag, value in info.items():
                decoded = TAGS.get(tag, tag)
                ret["EXIF:" + str(decoded)] = value
            return ret
        else:
            if mime_type != "application/pdf":
                content = self.to_pdf(digest, content, mime_type)

            with make_temp_file(content) as in_fn:
                try:
                    output = subprocess.check_output(["pdfinfo", in_fn])
                except OSError:
                    logger.error("Conversion failed, probably pdfinfo is not installed")
                    raise

            ret = {}
            for line in output.split(b"\n"):
                if b":" in line:
                    key, value = line.strip().split(b":", 1)
                    key = str(key)
                    ret["PDF:" + key] = str(value.strip(), errors="replace")

            return ret


Instruction:
Here you have a function in Python 3, explain what it does
def ToByteArray(self):
    lc = self.InternalEncodeLc()
    out = bytearray(4)  # will extend

    out[0] = self.cla
    out[1] = self.ins
    out[2] = self.p1
    out[3] = self.p2
    if self.data:
      out.extend(lc)
      out.extend(self.data)
      out.extend([0x00, 0x00])  # Le
    else:
      out.extend([0x00, 0x00, 0x00])  # Le
    return out

Response:
Serialize the command.

    Encodes the command as per the U2F specs, using the standard
    ISO 7816-4 extended encoding.  All Commands expect data, so
    Le is always present.

    Returns:
      Python bytearray of the encoded command.


Instruction:
Write a Python 3 script to
authenticate the user with the challenge_data.

Response:
def Authenticate(self, app_id, challenge_data,
                   print_callback=sys.stderr.write):
    """See base class."""

    # Ensure environment variable is present
    plugin_cmd = os.environ.get(SK_SIGNING_PLUGIN_ENV_VAR)
    if plugin_cmd is None:
      raise errors.PluginError('{} env var is not set'
                               .format(SK_SIGNING_PLUGIN_ENV_VAR))

    # Prepare input to signer
    client_data_map, signing_input = self._BuildPluginRequest(
        app_id, challenge_data, self.origin)

    # Call plugin
    print_callback('Please insert and touch your security key\n')
    response = self._CallPlugin([plugin_cmd], signing_input)

    # Handle response
    key_challenge_pair = (response['keyHandle'], response['challengeHash'])
    client_data_json = client_data_map[key_challenge_pair]
    client_data = client_data_json.encode()
    return self._BuildAuthenticatorResponse(app_id, client_data, response)


Instruction:
Implement a Python 3 function for
building a JSON request for the plugin.

Response:
def _BuildPluginRequest(self, app_id, challenge_data, origin):
    """Builds a JSON request in the form that the plugin expects."""
    client_data_map = {}
    encoded_challenges = []
    app_id_hash_encoded = self._Base64Encode(self._SHA256(app_id))
    for challenge_item in challenge_data:
      key = challenge_item['key']
      key_handle_encoded = self._Base64Encode(key.key_handle)

      raw_challenge = challenge_item['challenge']

      client_data_json = model.ClientData(
          model.ClientData.TYP_AUTHENTICATION,
          raw_challenge,
          origin).GetJson()

      challenge_hash_encoded = self._Base64Encode(
          self._SHA256(client_data_json))

      # Populate challenges list
      encoded_challenges.append({
          'appIdHash': app_id_hash_encoded,
          'challengeHash': challenge_hash_encoded,
          'keyHandle': key_handle_encoded,
          'version': key.version,
      })

      # Populate ClientData map
      key_challenge_pair = (key_handle_encoded, challenge_hash_encoded)
      client_data_map[key_challenge_pair] = client_data_json

    signing_request = {
        'type': 'sign_helper_request',
        'signData': encoded_challenges,
        'timeoutSeconds': U2F_SIGNATURE_TIMEOUT_SECONDS,
        'localAlways': True
    }

    return client_data_map, json.dumps(signing_request)


Instruction:
Can you generate the documentation for the following Python 3 function
def _BuildAuthenticatorResponse(self, app_id, client_data, plugin_response):
    encoded_client_data = self._Base64Encode(client_data)
    signature_data = str(plugin_response['signatureData'])
    key_handle = str(plugin_response['keyHandle'])

    response = {
        'clientData': encoded_client_data,
        'signatureData': signature_data,
        'applicationId': app_id,
        'keyHandle': key_handle,
    }
    return response

Response: Builds the response to return to the caller.


Instruction:
Can you implement a function in Python 3 that
calls the plugin and validates the response.

Response:
def _CallPlugin(self, cmd, input_json):
    """Calls the plugin and validates the response."""
    # Calculate length of input
    input_length = len(input_json)
    length_bytes_le = struct.pack('<I', input_length)
    request = length_bytes_le + input_json.encode()

    # Call plugin
    sign_process = subprocess.Popen(cmd,
                                    stdin=subprocess.PIPE,
                                    stdout=subprocess.PIPE)

    stdout = sign_process.communicate(request)[0]
    exit_status = sign_process.wait()

    # Parse and validate response size
    response_len_le = stdout[:4]
    response_len = struct.unpack('<I', response_len_le)[0]
    response = stdout[4:]
    if response_len != len(response):
      raise errors.PluginError(
          'Plugin response length {} does not match data {} (exit_status={})'
          .format(response_len, len(response), exit_status))

    # Ensure valid json
    try:
      json_response = json.loads(response.decode())
    except ValueError:
      raise errors.PluginError('Plugin returned invalid output (exit_status={})'
                               .format(exit_status))

    # Ensure response type
    if json_response.get('type') != 'sign_helper_reply':
      raise errors.PluginError('Plugin returned invalid response type '
                               '(exit_status={})'
                               .format(exit_status))

    # Parse response codes
    result_code = json_response.get('code')
    if result_code is None:
      raise errors.PluginError('Plugin missing result code (exit_status={})'
                               .format(exit_status))

    # Handle errors
    if result_code == SK_SIGNING_PLUGIN_TOUCH_REQUIRED:
      raise errors.U2FError(errors.U2FError.TIMEOUT)
    elif result_code == SK_SIGNING_PLUGIN_WRONG_DATA:
      raise errors.U2FError(errors.U2FError.DEVICE_INELIGIBLE)
    elif result_code != SK_SIGNING_PLUGIN_NO_ERROR:
      raise errors.PluginError(
          'Plugin failed with error {} - {} (exit_status={})'
          .format(result_code,
                  json_response.get('errorDetail'),
                  exit_status))

    # Ensure response data is present
    response_data = json_response.get('responseData')
    if response_data is None:
      raise errors.PluginErrors(
          'Plugin returned output with missing responseData (exit_status={})'
          .format(exit_status))

    return response_data


Instruction:
Explain what the following Python 3 code does
def InternalInit(self):
    self.cid = UsbHidTransport.U2FHID_BROADCAST_CID
    nonce = bytearray(os.urandom(8))
    r = self.InternalExchange(UsbHidTransport.U2FHID_INIT, nonce)
    if len(r) < 17:
      raise errors.HidError('unexpected init reply len')
    if r[0:8] != nonce:
      raise errors.HidError('nonce mismatch')
    self.cid = bytearray(r[8:12])

    self.u2fhid_version = r[12]

Response: Initializes the device and obtains channel id.


Instruction:
How would you code a function in Python 3 to
send and receives a message from the device.

Response:
def InternalExchange(self, cmd, payload_in):
    """Sends and receives a message from the device."""
    # make a copy because we destroy it below
    self.logger.debug('payload: ' + str(list(payload_in)))
    payload = bytearray()
    payload[:] = payload_in
    for _ in range(2):
      self.InternalSend(cmd, payload)
      ret_cmd, ret_payload = self.InternalRecv()

      if ret_cmd == UsbHidTransport.U2FHID_ERROR:
        if ret_payload == UsbHidTransport.ERR_CHANNEL_BUSY:
          time.sleep(0.5)
          continue
        raise errors.HidError('Device error: %d' % int(ret_payload[0]))
      elif ret_cmd != cmd:
        raise errors.HidError('Command mismatch!')

      return ret_payload
    raise errors.HidError('Device Busy.  Please retry')


Instruction:
Write a Python 3 script to
send a message to the device including fragmenting it.

Response:
def InternalSend(self, cmd, payload):
    """Sends a message to the device, including fragmenting it."""
    length_to_send = len(payload)

    max_payload = self.packet_size - 7
    first_frame = payload[0:max_payload]
    first_packet = UsbHidTransport.InitPacket(self.packet_size, self.cid, cmd,
                                              len(payload), first_frame)
    del payload[0:max_payload]
    length_to_send -= len(first_frame)
    self.InternalSendPacket(first_packet)

    seq = 0
    while length_to_send > 0:
      max_payload = self.packet_size - 5
      next_frame = payload[0:max_payload]
      del payload[0:max_payload]
      length_to_send -= len(next_frame)
      next_packet = UsbHidTransport.ContPacket(self.packet_size, self.cid, seq,
                                               next_frame)
      self.InternalSendPacket(next_packet)
      seq += 1


Instruction:
Write a Python 3 script to
receive a message from the device including defragmenting it.

Response:
def InternalRecv(self):
    """Receives a message from the device, including defragmenting it."""
    first_read = self.InternalReadFrame()
    first_packet = UsbHidTransport.InitPacket.FromWireFormat(self.packet_size,
                                                             first_read)

    data = first_packet.payload
    to_read = first_packet.size - len(first_packet.payload)

    seq = 0
    while to_read > 0:
      next_read = self.InternalReadFrame()
      next_packet = UsbHidTransport.ContPacket.FromWireFormat(self.packet_size,
                                                              next_read)
      if self.cid != next_packet.cid:
        # Skip over packets that are for communication with other clients.
        # HID is broadcast, so we see potentially all communication from the
        # device.  For well-behaved devices, these should be BUSY messages
        # sent to other clients of the device because at this point we're
        # in mid-message transit.
        continue

      if seq != next_packet.seq:
        raise errors.HardwareError('Packets received out of order')

      # This packet for us at this point, so debit it against our
      # balance of bytes to read.
      to_read -= len(next_packet.payload)

      data.extend(next_packet.payload)
      seq += 1

    # truncate incomplete frames
    data = data[0:first_packet.size]
    return (first_packet.cmd, data)


Instruction:
Write a Python 3 function for
authenticating the user with the given application ID.

Response:
def Authenticate(self, app_id, challenge_data,
                   print_callback=sys.stderr.write):
    """See base class."""
    # If authenticator is not plugged in, prompt
    try:
      device = u2f.GetLocalU2FInterface(origin=self.origin)
    except errors.NoDeviceFoundError:
      print_callback('Please insert your security key and press enter...')
      six.moves.input()
      device = u2f.GetLocalU2FInterface(origin=self.origin)

    print_callback('Please touch your security key.\n')

    for challenge_item in challenge_data:
      raw_challenge = challenge_item['challenge']
      key = challenge_item['key']

      try:
        result = device.Authenticate(app_id, raw_challenge, [key])
      except errors.U2FError as e:
        if e.code == errors.U2FError.DEVICE_INELIGIBLE:
          continue
        else:
          raise

      client_data = self._base64encode(result.client_data.GetJson().encode())
      signature_data = self._base64encode(result.signature_data)
      key_handle = self._base64encode(result.key_handle)

      return {
          'clientData': client_data,
          'signatureData': signature_data,
          'applicationId': app_id,
          'keyHandle': key_handle,
      }

    raise errors.U2FError(errors.U2FError.DEVICE_INELIGIBLE)


Instruction:
Here you have a function in Python 3, explain what it does
def InternalPlatformSwitch(funcname, *args, **kwargs):
  # pylint: disable=g-import-not-at-top
  clz = None
  if sys.platform.startswith('linux'):
    from pyu2f.hid import linux
    clz = linux.LinuxHidDevice
  elif sys.platform.startswith('win32'):
    from pyu2f.hid import windows
    clz = windows.WindowsHidDevice
  elif sys.platform.startswith('darwin'):
    from pyu2f.hid import macos
    clz = macos.MacOsHidDevice

  if not clz:
    raise Exception('Unsupported platform: ' + sys.platform)

  if funcname == '__init__':
    return clz(*args, **kwargs)
  return getattr(clz, funcname)(*args, **kwargs)

Response: Determine on a platform - specific basis which module to use.


Instruction:
Implement a function in Python 3 to
return JSON version of ClientData compatible with FIDO spec.

Response:
def GetJson(self):
    """Returns JSON version of ClientData compatible with FIDO spec."""

    # The U2F Raw Messages specification specifies that the challenge is encoded
    # with URL safe Base64 without padding encoding specified in RFC 4648.
    # Python does not natively support a paddingless encoding, so we simply
    # remove the padding from the end of the string.
    server_challenge_b64 = base64.urlsafe_b64encode(
        self.raw_server_challenge).decode()
    server_challenge_b64 = server_challenge_b64.rstrip('=')
    return json.dumps({'typ': self.typ,
                       'challenge': server_challenge_b64,
                       'origin': self.origin}, sort_keys=True)


Instruction:
How would you implement a function in Python 3 that
gets the length of a value in a report descriptor.

Response:
def GetValueLength(rd, pos):
  """Get value length for a key in rd.

  For a key at position pos in the Report Descriptor rd, return the length
  of the associated value.  This supports both short and long format
  values.

  Args:
    rd: Report Descriptor
    pos: The position of the key in rd.

  Returns:
    (key_size, data_len) where key_size is the number of bytes occupied by
    the key and data_len is the length of the value associated by the key.
  """
  rd = bytearray(rd)
  key = rd[pos]
  if key == LONG_ITEM_ENCODING:
    # If the key is tagged as a long item (0xfe), then the format is
    # [key (1 byte)] [data len (1 byte)] [item tag (1 byte)] [data (n # bytes)].
    # Thus, the entire key record is 3 bytes long.
    if pos + 1 < len(rd):
      return (3, rd[pos + 1])
    else:
      raise errors.HidError('Malformed report descriptor')

  else:
    # If the key is tagged as a short item, then the item tag and data len are
    # packed into one byte.  The format is thus:
    # [tag (high 4 bits)] [type (2 bits)] [size code (2 bits)] [data (n bytes)].
    # The size code specifies 1,2, or 4 bytes (0x03 means 4 bytes).
    code = key & 0x03
    if code <= 0x02:
      return (1, code)
    elif code == 0x03:
      return (1, 4)

  raise errors.HidError('Cannot happen')


Instruction:
How would you explain what the following Python 3 function does
def ReadLsbBytes(rd, offset, value_size):

  encoding = None
  if value_size == 1:
    encoding = '<B'
  elif value_size == 2:
    encoding = '<H'
  elif value_size == 4:
    encoding = '<L'
  else:
    raise errors.HidError('Invalid value size specified')

  ret, = struct.unpack(encoding, rd[offset:offset + value_size])
  return ret

Response: Reads value_size bytes from rd at offset least signifcant byte first.


Instruction:
Write a Python 3 function for
parsing the binary report descriptor into a DeviceDescriptor object.

Response:
def ParseReportDescriptor(rd, desc):
  """Parse the binary report descriptor.

  Parse the binary report descriptor into a DeviceDescriptor object.

  Args:
    rd: The binary report descriptor
    desc: The DeviceDescriptor object to update with the results
        from parsing the descriptor.

  Returns:
    None
  """
  rd = bytearray(rd)

  pos = 0
  report_count = None
  report_size = None
  usage_page = None
  usage = None

  while pos < len(rd):
    key = rd[pos]

    # First step, determine the value encoding (either long or short).
    key_size, value_length = GetValueLength(rd, pos)

    if key & REPORT_DESCRIPTOR_KEY_MASK == INPUT_ITEM:
      if report_count and report_size:
        byte_length = (report_count * report_size) // 8
        desc.internal_max_in_report_len = max(
            desc.internal_max_in_report_len, byte_length)
        report_count = None
        report_size = None
    elif key & REPORT_DESCRIPTOR_KEY_MASK == OUTPUT_ITEM:
      if report_count and report_size:
        byte_length = (report_count * report_size) // 8
        desc.internal_max_out_report_len = max(
            desc.internal_max_out_report_len, byte_length)
        report_count = None
        report_size = None
    elif key & REPORT_DESCRIPTOR_KEY_MASK == COLLECTION_ITEM:
      if usage_page:
        desc.usage_page = usage_page
      if usage:
        desc.usage = usage
    elif key & REPORT_DESCRIPTOR_KEY_MASK == REPORT_COUNT:
      if len(rd) >= pos + 1 + value_length:
        report_count = ReadLsbBytes(rd, pos + 1, value_length)
    elif key & REPORT_DESCRIPTOR_KEY_MASK == REPORT_SIZE:
      if len(rd) >= pos + 1 + value_length:
        report_size = ReadLsbBytes(rd, pos + 1, value_length)
    elif key & REPORT_DESCRIPTOR_KEY_MASK == USAGE_PAGE:
      if len(rd) >= pos + 1 + value_length:
        usage_page = ReadLsbBytes(rd, pos + 1, value_length)
    elif key & REPORT_DESCRIPTOR_KEY_MASK == USAGE:
      if len(rd) >= pos + 1 + value_length:
        usage = ReadLsbBytes(rd, pos + 1, value_length)

    pos += value_length + key_size
  return desc


Instruction:
Write a Python 3 function for
writing packet to the device.

Response:
def Write(self, packet):
    """See base class."""
    out = bytearray([0] + packet)  # Prepend the zero-byte (report ID)
    os.write(self.dev, out)


Instruction:
Write a Python 3 script to
read the next chunk of data from the device.

Response:
def Read(self):
    """See base class."""
    raw_in = os.read(self.dev, self.GetInReportDataLength())
    decoded_in = list(bytearray(raw_in))
    return decoded_in


Instruction:
Make a summary of the following Python 3 code
def FillDeviceAttributes(device, descriptor):
  attributes = HidAttributes()
  result = hid.HidD_GetAttributes(device, ctypes.byref(attributes))
  if not result:
    raise ctypes.WinError()

  buf = ctypes.create_string_buffer(1024)
  result = hid.HidD_GetProductString(device, buf, 1024)

  if not result:
    raise ctypes.WinError()

  descriptor.vendor_id = attributes.VendorID
  descriptor.product_id = attributes.ProductID
  descriptor.product_string = ctypes.wstring_at(buf)

Response: Fills out the attributes of the device into the device descriptor.


Instruction:
How would you code a function in Python 3 to
fill out the HidCapabilitites of the device into the device descriptor.

Response:
def FillDeviceCapabilities(device, descriptor):
  """Fill out device capabilities.

  Fills the HidCapabilitites of the device into descriptor.

  Args:
    device: A handle to the open device
    descriptor: DeviceDescriptor to populate with the
      capabilities

  Returns:
    none

  Raises:
    WindowsError when unable to obtain capabilitites.
  """
  preparsed_data = PHIDP_PREPARSED_DATA(0)
  ret = hid.HidD_GetPreparsedData(device, ctypes.byref(preparsed_data))
  if not ret:
    raise ctypes.WinError()

  try:
    caps = HidCapabilities()
    ret = hid.HidP_GetCaps(preparsed_data, ctypes.byref(caps))

    if ret != HIDP_STATUS_SUCCESS:
      raise ctypes.WinError()

    descriptor.usage = caps.Usage
    descriptor.usage_page = caps.UsagePage
    descriptor.internal_max_in_report_len = caps.InputReportByteLength
    descriptor.internal_max_out_report_len = caps.OutputReportByteLength

  finally:
    hid.HidD_FreePreparsedData(preparsed_data)


Instruction:
Make a summary of the following Python 3 code
def OpenDevice(path, enum=False):
  desired_access = GENERIC_WRITE | GENERIC_READ
  share_mode = FILE_SHARE_READ | FILE_SHARE_WRITE
  if enum:
    desired_access = 0

  h = kernel32.CreateFileA(path,
                           desired_access,
                           share_mode,
                           None, OPEN_EXISTING, 0, None)
  if h == INVALID_HANDLE_VALUE:
    raise ctypes.WinError()
  return h

Response: Open the device and return a handle to it.


Instruction:
Write a Python 3 script for
enumerating the available devices.

Response:
def Enumerate():
    """See base class."""
    hid_guid = GUID()
    hid.HidD_GetHidGuid(ctypes.byref(hid_guid))

    devices = setupapi.SetupDiGetClassDevsA(
        ctypes.byref(hid_guid), None, None, 0x12)
    index = 0
    interface_info = DeviceInterfaceData()
    interface_info.cbSize = ctypes.sizeof(DeviceInterfaceData)  # pylint: disable=invalid-name

    out = []
    while True:
      result = setupapi.SetupDiEnumDeviceInterfaces(
          devices, 0, ctypes.byref(hid_guid), index,
          ctypes.byref(interface_info))
      index += 1
      if not result:
        break

      detail_len = wintypes.DWORD()
      result = setupapi.SetupDiGetDeviceInterfaceDetailA(
          devices, ctypes.byref(interface_info), None, 0,
          ctypes.byref(detail_len), None)

      detail_len = detail_len.value
      if detail_len == 0:
        # skip this device, some kind of error
        continue

      buf = ctypes.create_string_buffer(detail_len)
      interface_detail = DeviceInterfaceDetailData.from_buffer(buf)
      interface_detail.cbSize = ctypes.sizeof(DeviceInterfaceDetailData)

      result = setupapi.SetupDiGetDeviceInterfaceDetailA(
          devices, ctypes.byref(interface_info),
          ctypes.byref(interface_detail), detail_len, None, None)

      if not result:
        raise ctypes.WinError()

      descriptor = base.DeviceDescriptor()
      # This is a bit of a hack to work around a limitation of ctypes and
      # "header" structures that are common in windows.  DevicePath is a
      # ctypes array of length 1, but it is backed with a buffer that is much
      # longer and contains a null terminated string.  So, we read the null
      # terminated string off DevicePath here.  Per the comment above, the
      # alignment of this struct varies depending on architecture, but
      # in all cases the path string starts 1 DWORD into the structure.
      #
      # The path length is:
      #   length of detail buffer - header length (1 DWORD)
      path_len = detail_len - ctypes.sizeof(wintypes.DWORD)
      descriptor.path = ctypes.string_at(
          ctypes.addressof(interface_detail.DevicePath), path_len)

      device = None
      try:
        device = OpenDevice(descriptor.path, True)
      except WindowsError as e:  # pylint: disable=undefined-variable
        if e.winerror == ERROR_ACCESS_DENIED:  # Access Denied, e.g. a keyboard
          continue
        else:
          raise e

      try:
        FillDeviceAttributes(device, descriptor)
        FillDeviceCapabilities(device, descriptor)
        out.append(descriptor.ToPublicDict())
      finally:
        kernel32.CloseHandle(device)

    return out


Instruction:
Can you tell what is the following Python 3 function doing
def Write(self, packet):
    if len(packet) != self.GetOutReportDataLength():
      raise errors.HidError("Packet length must match report data length.")

    packet_data = [0] + packet  # Prepend the zero-byte (report ID)
    out = bytes(bytearray(packet_data))
    num_written = wintypes.DWORD()
    ret = (
        kernel32.WriteFile(
            self.dev, out, len(out),
            ctypes.byref(num_written), None))
    if num_written.value != len(out):
      raise errors.HidError(
          "Failed to write complete packet.  " + "Expected %d, but got %d" %
          (len(out), num_written.value))
    if not ret:
      raise ctypes.WinError()

Response: Writes a packet to the report.


Instruction:
Can you implement a function in Python 3 that
reads the next report from the device.

Response:
def Read(self):
    """See base class."""
    buf = ctypes.create_string_buffer(self.desc.internal_max_in_report_len)
    num_read = wintypes.DWORD()
    ret = kernel32.ReadFile(
        self.dev, buf, len(buf), ctypes.byref(num_read), None)

    if num_read.value != self.desc.internal_max_in_report_len:
      raise errors.HidError("Failed to read full length report from device.")

    if not ret:
      raise ctypes.WinError()

    # Convert the string buffer to a list of numbers.  Throw away the first
    # byte, which is the report id (which we don't care about).
    return list(bytearray(buf[1:]))


Instruction:
Write a Python 3 script for
authenticating the user with the challenge data.

Response:
def Authenticate(self, app_id, challenge_data,
                   print_callback=sys.stderr.write):
    """See base class."""
    for authenticator in self.authenticators:
      if authenticator.IsAvailable():
        result = authenticator.Authenticate(app_id,
                                            challenge_data,
                                            print_callback)
        return result

    raise ValueError('No valid authenticators found')


Instruction:
Can you tell what is the following Python 3 function doing
def GetLocalU2FInterface(origin=socket.gethostname()):
  hid_transports = hidtransport.DiscoverLocalHIDU2FDevices()
  for t in hid_transports:
    try:
      return U2FInterface(security_key=hardware.SecurityKey(transport=t),
                          origin=origin)
    except errors.UnsupportedVersionException:
      # Skip over devices that don't speak the proper version of the protocol.
      pass

  # Unable to find a device
  raise errors.NoDeviceFoundError()

Response: Obtains a U2FInterface for the first valid local U2FHID device found.


Instruction:
Make a summary of the following Python 3 code
def Register(self, app_id, challenge, registered_keys):
    client_data = model.ClientData(model.ClientData.TYP_REGISTRATION, challenge,
                                   self.origin)
    challenge_param = self.InternalSHA256(client_data.GetJson())
    app_param = self.InternalSHA256(app_id)

    for key in registered_keys:
      try:
        # skip non U2F_V2 keys
        if key.version != u'U2F_V2':
          continue
        resp = self.security_key.CmdAuthenticate(challenge_param, app_param,
                                                 key.key_handle, True)
        # check_only mode CmdAuthenticate should always raise some
        # exception
        raise errors.HardwareError('Should Never Happen')

      except errors.TUPRequiredError:
        # This indicates key was valid.  Thus, no need to register
        raise errors.U2FError(errors.U2FError.DEVICE_INELIGIBLE)
      except errors.InvalidKeyHandleError as e:
        # This is the case of a key for a different token, so we just ignore it.
        pass
      except errors.HardwareError as e:
        raise errors.U2FError(errors.U2FError.BAD_REQUEST, e)

    # Now register the new key
    for _ in range(30):
      try:
        resp = self.security_key.CmdRegister(challenge_param, app_param)
        return model.RegisterResponse(resp, client_data)
      except errors.TUPRequiredError as e:
        self.security_key.CmdWink()
        time.sleep(0.5)
      except errors.HardwareError as e:
        raise errors.U2FError(errors.U2FError.BAD_REQUEST, e)

    raise errors.U2FError(errors.U2FError.TIMEOUT)

Response: Registers the app_id with the security key.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def Authenticate(self, app_id, challenge, registered_keys):
    client_data = model.ClientData(model.ClientData.TYP_AUTHENTICATION,
                                   challenge, self.origin)
    app_param = self.InternalSHA256(app_id)
    challenge_param = self.InternalSHA256(client_data.GetJson())
    num_invalid_keys = 0
    for key in registered_keys:
      try:
        if key.version != u'U2F_V2':
          continue
        for _ in range(30):
          try:
            resp = self.security_key.CmdAuthenticate(challenge_param, app_param,
                                                     key.key_handle)
            return model.SignResponse(key.key_handle, resp, client_data)
          except errors.TUPRequiredError:
            self.security_key.CmdWink()
            time.sleep(0.5)
      except errors.InvalidKeyHandleError:
        num_invalid_keys += 1
        continue
      except errors.HardwareError as e:
        raise errors.U2FError(errors.U2FError.BAD_REQUEST, e)

    if num_invalid_keys == len(registered_keys):
      # In this case, all provided keys were invalid.
      raise errors.U2FError(errors.U2FError.DEVICE_INELIGIBLE)

    # In this case, the TUP was not pressed.
    raise errors.U2FError(errors.U2FError.TIMEOUT)

Response: Authenticates app_id with the security key.


Instruction:
Explain what the following Python 3 code does
def CmdRegister(self, challenge_param, app_param):
    self.logger.debug('CmdRegister')
    if len(challenge_param) != 32 or len(app_param) != 32:
      raise errors.InvalidRequestError()

    body = bytearray(challenge_param + app_param)
    response = self.InternalSendApdu(apdu.CommandApdu(
        0,
        apdu.CMD_REGISTER,
        0x03,  # Per the U2F reference code tests
        0x00,
        body))
    response.CheckSuccessOrRaise()

    return response.body

Response: This function is used to register a security key with a particular origin & client.


Instruction:
Make a summary of the following Python 3 code
def CmdAuthenticate(self,
                      challenge_param,
                      app_param,
                      key_handle,
                      check_only=False):
    """Attempt to obtain an authentication signature.

    Ask the security key to sign a challenge for a particular key handle
    in order to authenticate the user.

    Args:
      challenge_param: SHA-256 hash of client_data object as a bytes
          object.
      app_param: SHA-256 hash of the app id as a bytes object.
      key_handle: The key handle to use to issue the signature as a bytes
          object.
      check_only: If true, only check if key_handle is valid.

    Returns:
      A binary structure containing the key handle, attestation, and a
      signature over that by the attestation key.  The precise format
      is dictated by the FIDO U2F specs.

    Raises:
      TUPRequiredError: If check_only is False, a Test of User Precense
          is required to proceed.  If check_only is True, this means
          the key_handle is valid.
      InvalidKeyHandleError: The key_handle is not valid for this device.
      ApduError: Something else went wrong on the device.
    """
    self.logger.debug('CmdAuthenticate')
    if len(challenge_param) != 32 or len(app_param) != 32:
      raise errors.InvalidRequestError()
    control = 0x07 if check_only else 0x03

    body = bytearray(challenge_param + app_param +
                     bytearray([len(key_handle)]) + key_handle)
    response = self.InternalSendApdu(apdu.CommandApdu(
        0, apdu.CMD_AUTH, control, 0x00, body))
    response.CheckSuccessOrRaise()

    return response.body

Response: This function is used to request an authentication signature over a particular key handle.


Instruction:
Write a Python 3 script for
obtaining the version of the device and test transport format. Obtains the version of the device and determines whether to use ISO 7816-4 or the U2f variant. This function should be called at least once before CmdAuthenticate or CmdRegister to make sure the object is using the proper transport for the device. Returns: The version of the U2F protocol in use.

Response:
def CmdVersion(self):
    """Obtain the version of the device and test transport format.

    Obtains the version of the device and determines whether to use ISO
    7816-4 or the U2f variant.  This function should be called at least once
    before CmdAuthenticate or CmdRegister to make sure the object is using the
    proper transport for the device.

    Returns:
      The version of the U2F protocol in use.
    """
    self.logger.debug('CmdVersion')
    response = self.InternalSendApdu(apdu.CommandApdu(
        0, apdu.CMD_VERSION, 0x00, 0x00))

    if not response.IsSuccess():
      raise errors.ApduError(response.sw1, response.sw2)

    return response.body


Instruction:
Write a Python 3 function that can
send an APDU to the device.

Response:
def InternalSendApdu(self, apdu_to_send):
    """Send an APDU to the device.

    Sends an APDU to the device, possibly falling back to the legacy
    encoding format that is not ISO7816-4 compatible.

    Args:
      apdu_to_send: The CommandApdu object to send

    Returns:
      The ResponseApdu object constructed out of the devices reply.
    """
    response = None
    if not self.use_legacy_format:
      response = apdu.ResponseApdu(self.transport.SendMsgBytes(
          apdu_to_send.ToByteArray()))
      if response.sw1 == 0x67 and response.sw2 == 0x00:
        # If we failed using the standard format, retry with the
        # legacy format.
        self.use_legacy_format = True
        return self.InternalSendApdu(apdu_to_send)
    else:
      response = apdu.ResponseApdu(self.transport.SendMsgBytes(
          apdu_to_send.ToLegacyU2FByteArray()))
    return response


Instruction:
Can you implement a function in Python 3 that
reads int property from the HID device.

Response:
def GetDeviceIntProperty(dev_ref, key):
  """Reads int property from the HID device."""
  cf_key = CFStr(key)
  type_ref = iokit.IOHIDDeviceGetProperty(dev_ref, cf_key)
  cf.CFRelease(cf_key)
  if not type_ref:
    return None

  if cf.CFGetTypeID(type_ref) != cf.CFNumberGetTypeID():
    raise errors.OsHidError('Expected number type, got {}'.format(
        cf.CFGetTypeID(type_ref)))

  out = ctypes.c_int32()
  ret = cf.CFNumberGetValue(type_ref, K_CF_NUMBER_SINT32_TYPE,
                            ctypes.byref(out))
  if not ret:
    return None

  return out.value


Instruction:
Can you implement a function in Python 3 that
reads string property from the HID device.

Response:
def GetDeviceStringProperty(dev_ref, key):
  """Reads string property from the HID device."""
  cf_key = CFStr(key)
  type_ref = iokit.IOHIDDeviceGetProperty(dev_ref, cf_key)
  cf.CFRelease(cf_key)
  if not type_ref:
    return None

  if cf.CFGetTypeID(type_ref) != cf.CFStringGetTypeID():
    raise errors.OsHidError('Expected string type, got {}'.format(
        cf.CFGetTypeID(type_ref)))

  type_ref = ctypes.cast(type_ref, CF_STRING_REF)
  out = ctypes.create_string_buffer(DEVICE_STRING_PROPERTY_BUFFER_SIZE)
  ret = cf.CFStringGetCString(type_ref, out, DEVICE_STRING_PROPERTY_BUFFER_SIZE,
                              K_CF_STRING_ENCODING_UTF8)
  if not ret:
    return None

  return out.value.decode('utf8')


Instruction:
Make a summary of the following Python 3 code
def GetDevicePath(device_handle):
  # Obtain device path from IO Registry
  io_service_obj = iokit.IOHIDDeviceGetService(device_handle)
  str_buffer = ctypes.create_string_buffer(DEVICE_PATH_BUFFER_SIZE)
  iokit.IORegistryEntryGetPath(io_service_obj, K_IO_SERVICE_PLANE, str_buffer)

  return str_buffer.value

Response: Retrieves the unique path for the device.


Instruction:
Explain what the following Python 3 code does
def HidReadCallback(read_queue, result, sender, report_type, report_id, report,
                    report_length):
  """Handles incoming IN report from HID device."""
  del result, sender, report_type, report_id  # Unused by the callback function

  incoming_bytes = [report[i] for i in range(report_length)]
  read_queue.put(incoming_bytes)

Response: Handles incoming IN report from HID device.


Instruction:
Write a Python 3 script for
binding a device to the run loop and starts the run loop.

Response:
def DeviceReadThread(hid_device):
  """Binds a device to the thread's run loop, then starts the run loop.

  Args:
    hid_device: The MacOsHidDevice object

  The HID manager requires a run loop to handle Report reads. This thread
  function serves that purpose.
  """

  # Schedule device events with run loop
  hid_device.run_loop_ref = cf.CFRunLoopGetCurrent()
  if not hid_device.run_loop_ref:
    logger.error('Failed to get current run loop')
    return

  iokit.IOHIDDeviceScheduleWithRunLoop(hid_device.device_handle,
                                       hid_device.run_loop_ref,
                                       K_CF_RUNLOOP_DEFAULT_MODE)

  # Run the run loop
  run_loop_run_result = K_CF_RUN_LOOP_RUN_TIMED_OUT
  while (run_loop_run_result == K_CF_RUN_LOOP_RUN_TIMED_OUT or
         run_loop_run_result == K_CF_RUN_LOOP_RUN_HANDLED_SOURCE):
    run_loop_run_result = cf.CFRunLoopRunInMode(
        K_CF_RUNLOOP_DEFAULT_MODE,
        1000,  # Timeout in seconds
        False)  # Return after source handled

  # log any unexpected run loop exit
  if run_loop_run_result != K_CF_RUN_LOOP_RUN_STOPPED:
    logger.error('Unexpected run loop exit code: %d', run_loop_run_result)

  # Unschedule from run loop
  iokit.IOHIDDeviceUnscheduleFromRunLoop(hid_device.device_handle,
                                         hid_device.run_loop_ref,
                                         K_CF_RUNLOOP_DEFAULT_MODE)


Instruction:
Here you have a function in Python 3, explain what it does
def Enumerate():
    # Init a HID manager
    hid_mgr = iokit.IOHIDManagerCreate(None, None)
    if not hid_mgr:
      raise errors.OsHidError('Unable to obtain HID manager reference')
    iokit.IOHIDManagerSetDeviceMatching(hid_mgr, None)

    # Get devices from HID manager
    device_set_ref = iokit.IOHIDManagerCopyDevices(hid_mgr)
    if not device_set_ref:
      raise errors.OsHidError('Failed to obtain devices from HID manager')

    num = iokit.CFSetGetCount(device_set_ref)
    devices = (IO_HID_DEVICE_REF * num)()
    iokit.CFSetGetValues(device_set_ref, devices)

    # Retrieve and build descriptor dictionaries for each device
    descriptors = []
    for dev in devices:
      d = base.DeviceDescriptor()
      d.vendor_id = GetDeviceIntProperty(dev, HID_DEVICE_PROPERTY_VENDOR_ID)
      d.product_id = GetDeviceIntProperty(dev, HID_DEVICE_PROPERTY_PRODUCT_ID)
      d.product_string = GetDeviceStringProperty(dev,
                                                 HID_DEVICE_PROPERTY_PRODUCT)
      d.usage = GetDeviceIntProperty(dev, HID_DEVICE_PROPERTY_PRIMARY_USAGE)
      d.usage_page = GetDeviceIntProperty(
          dev, HID_DEVICE_PROPERTY_PRIMARY_USAGE_PAGE)
      d.report_id = GetDeviceIntProperty(dev, HID_DEVICE_PROPERTY_REPORT_ID)
      d.path = GetDevicePath(dev)
      descriptors.append(d.ToPublicDict())

    # Clean up CF objects
    cf.CFRelease(device_set_ref)
    cf.CFRelease(hid_mgr)

    return descriptors

Response: Enumerate the HID components of a single HID container.


Instruction:
Create a Python 3 function for
writing a report to device.

Response:
def Write(self, packet):
    """See base class."""
    report_id = 0
    out_report_buffer = (ctypes.c_uint8 * self.internal_max_out_report_len)()
    out_report_buffer[:] = packet[:]

    result = iokit.IOHIDDeviceSetReport(self.device_handle,
                                        K_IO_HID_REPORT_TYPE_OUTPUT,
                                        report_id,
                                        out_report_buffer,
                                        self.internal_max_out_report_len)

    # Non-zero status indicates failure
    if result != K_IO_RETURN_SUCCESS:
      raise errors.OsHidError('Failed to write report to device')


Instruction:
Implement a Python 3 function for
reading a single element from the read queue.

Response:
def Read(self):
    """See base class."""

    result = None
    while result is None:
        try:
            result = self.read_queue.get(timeout=60)
        except queue.Empty:
            continue

    return result


Instruction:
Write a Python 3 script for
rendering detailed model edit page.

Response:
def change_view(self, *args, **kwargs):
        """Renders detailed model edit page."""
        Hierarchy.init_hierarchy(self)

        self.hierarchy.hook_change_view(self, args, kwargs)

        return super(HierarchicalModelAdmin, self).change_view(*args, **kwargs)


Instruction:
Given the following Python 3 function, write the documentation
def action_checkbox(self, obj):
        if getattr(obj, Hierarchy.UPPER_LEVEL_MODEL_ATTR, False):
            return ''

        return super(HierarchicalModelAdmin, self).action_checkbox(obj)

Response:
Renders checkboxes.

        Disable checkbox for parent item navigation link.


Instruction:
Can you generate the documentation for the following Python 3 function
def hierarchy_nav(self, obj):

        result_repr = ''  # For items without children.
        ch_count = getattr(obj, Hierarchy.CHILD_COUNT_MODEL_ATTR, 0)

        is_parent_link = getattr(obj, Hierarchy.UPPER_LEVEL_MODEL_ATTR, False)

        if is_parent_link or ch_count:  # For items with children and parent links.
            icon = 'icon icon-folder'
            title = _('Objects inside: %s') % ch_count

            if is_parent_link:
                icon = 'icon icon-folder-up'
                title = _('Upper level')

            url = './'

            if obj.pk:
                url = '?%s=%s' % (Hierarchy.PARENT_ID_QS_PARAM, obj.pk)

            if self._current_changelist.is_popup:

                qs_get = copy(self._current_changelist._request.GET)

                try:
                    del qs_get[Hierarchy.PARENT_ID_QS_PARAM]

                except KeyError:
                    pass

                qs_get = qs_get.urlencode()
                url = ('%s&%s' if '?' in url else '%s?%s') % (url, qs_get)

            result_repr = format_html('', url, icon, force_text(title))

        return result_repr

Response: Renders hierarchy navigation elements.


Instruction:
Write a Python 3 function that can
construct a query set.

Response:
def get_queryset(self, request):
        """Constructs a query set.

        :param request:
        :return:
        """
        self._hierarchy.hook_get_queryset(self, request)

        return super(HierarchicalChangeList, self).get_queryset(request)


Instruction:
Can you tell what is the following Python 3 function doing
def get_results(self, request):
        super(HierarchicalChangeList, self).get_results(request)

        self._hierarchy.hook_get_results(self)

Response: Gets query set results.


Instruction:
Given the following Python 3 function, write the documentation
def check_field_exists(self, field_name):
        if not settings.DEBUG:
            return

        try:
            self.lookup_opts.get_field(field_name)

        except FieldDoesNotExist as e:
            raise AdmirarchyConfigurationError(e)

Response: Implements field exists check for debugging purposes.


Instruction:
How would you explain what the following Python 3 function does
def init_hierarchy(cls, model_admin):
        hierarchy = getattr(model_admin, 'hierarchy')

        if hierarchy:
            if not isinstance(hierarchy, Hierarchy):
                hierarchy = AdjacencyList()  # For `True` and etc. TODO heuristics maybe.

        else:
            hierarchy = NoHierarchy()

        model_admin.hierarchy = hierarchy

Response: Initializes model admin with hierarchy data.


Instruction:
How would you explain what the following Python 3 function does
def get_pid_from_request(cls, changelist, request):
        val = request.GET.get(cls.PARENT_ID_QS_PARAM, False)
        pid = val or None

        try:
            del changelist.params[cls.PARENT_ID_QS_PARAM]

        except KeyError:
            pass

        return pid

Response: Gets parent ID from query string.


Instruction:
Explain what the following Python 3 code does
def hook_get_queryset(self, changelist, request):
        changelist.check_field_exists(self.pid_field)
        self.pid = self.get_pid_from_request(changelist, request)
        changelist.params[self.pid_field] = self.pid

Response: Hooked by ChangeList. get_queryset.


Instruction:
How would you explain what the following Python 3 function does
def hook_get_results(self, changelist):
        result_list = list(changelist.result_list)

        if self.pid:
            # Render to upper level link.
            parent = changelist.model.objects.get(pk=self.pid)
            parent = changelist.model(pk=getattr(parent, self.pid_field_real, None))
            setattr(parent, self.UPPER_LEVEL_MODEL_ATTR, True)
            result_list = [parent] + result_list

        # Get children stats.
        kwargs_filter = {'%s__in' % self.pid_field: result_list}

        stats_qs = changelist.model.objects.filter(
            **kwargs_filter).values_list(self.pid_field).annotate(cnt=models.Count(self.pid_field))

        stats = {item[0]: item[1] for item in stats_qs}

        for item in result_list:

            if hasattr(item, self.CHILD_COUNT_MODEL_ATTR):
                continue

            try:
                setattr(item, self.CHILD_COUNT_MODEL_ATTR, stats[item.id])

            except KeyError:
                setattr(item, self.CHILD_COUNT_MODEL_ATTR, 0)

        changelist.result_list = result_list

Response: Hooked by ChangeList. get_results.


Instruction:
Can you generate the documentation for the following Python 3 function
def hook_get_queryset(self, changelist, request):
        changelist.check_field_exists(self.left_field)
        changelist.check_field_exists(self.right_field)
        self.pid = self.get_pid_from_request(changelist, request)

        # Get parent item first.
        qs = changelist.root_queryset

        if self.pid:
            self.parent = qs.get(pk=self.pid)
            changelist.params.update(self.get_immediate_children_filter(self.parent))

        else:
            changelist.params[self.level_field] = self.root_level
            self.parent = qs.get(**{key: val for key, val in changelist.params.items() if not key.startswith('_')})

Response: Hooked by ChangeList. get_queryset.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def read_file(fpath):
    with io.open(os.path.join(PATH_BASE, fpath)) as f:
        return f.read()

Response: Reads a file within package directories.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_version():
    contents = read_file(os.path.join('admirarchy', '__init__.py'))
    version = re.search('VERSION = \(([^)]+)\)', contents)
    version = version.group(1).replace(', ', '.').strip()
    return version

Response: Returns version number without module import


Instruction:
Create a Python 3 function to
process an incoming update from a remote NetworkTables

Response:
def process_update(self, update):
        """Process an incoming update from a remote NetworkTables"""
        data = json.loads(update)
        NetworkTables.getEntry(data["k"]).setValue(data["v"])


Instruction:
Can you generate the documentation for the following Python 3 function
def _send_update(self, data):
        if isinstance(data, dict):
            data = json.dumps(data)
        self.update_callback(data)

Response: Send a NetworkTables update via the stored send_update callback


Instruction:
Can you create a Python 3 function that
cleans up listeners that are no longer needed.

Response:
def close(self):
        """
        Clean up NetworkTables listeners
        """
        NetworkTables.removeGlobalListener(self._nt_on_change)
        NetworkTables.removeConnectionListener(self._nt_connected)


Instruction:
Explain what the following Python 3 code does
def get_lat_long_climate_zones(latitude, longitude):
    try:
        from shapely.geometry import Point
    except ImportError:  # pragma: no cover
        raise ImportError("Finding climate zone of lat/long points requires shapely.")

    (
        iecc_climate_zones,
        iecc_moisture_regimes,
        ba_climate_zones,
        ca_climate_zones,
    ) = cached_data.climate_zone_geometry

    point = Point(longitude, latitude)  # x,y
    climate_zones = {}
    for iecc_climate_zone, shape in iecc_climate_zones:
        if shape.contains(point):
            climate_zones["iecc_climate_zone"] = iecc_climate_zone
            break
    else:
        climate_zones["iecc_climate_zone"] = None

    for iecc_moisture_regime, shape in iecc_moisture_regimes:
        if shape.contains(point):
            climate_zones["iecc_moisture_regime"] = iecc_moisture_regime
            break
    else:
        climate_zones["iecc_moisture_regime"] = None

    for ba_climate_zone, shape in ba_climate_zones:
        if shape.contains(point):
            climate_zones["ba_climate_zone"] = ba_climate_zone
            break
    else:
        climate_zones["ba_climate_zone"] = None

    for ca_climate_zone, shape in ca_climate_zones:
        if shape.contains(point):
            climate_zones["ca_climate_zone"] = ca_climate_zone
            break
    else:
        climate_zones["ca_climate_zone"] = None

    return climate_zones

Response: Returns a dict of str climate zones that contain lat and long coordinates.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_zcta_metadata(zcta):
    conn = metadata_db_connection_proxy.get_connection()
    cur = conn.cursor()
    cur.execute(
        """
      select
        *
      from
        zcta_metadata
      where
        zcta_id = ?
    """,
        (zcta,),
    )
    row = cur.fetchone()
    if row is None:
        raise UnrecognizedZCTAError(zcta)
    return {col[0]: row[i] for i, col in enumerate(cur.description)}

Response: Get the metadata about a ZIP Code Tabulation Area.


Instruction:
Write a Python 3 script to
get latitude and longitude of the target ZCTA in the specified location.

Response:
def zcta_to_lat_long(zcta):
    """Get location of ZCTA centroid

    Retrieves latitude and longitude of centroid of ZCTA
    to use for matching with weather station.

    Parameters
    ----------
    zcta : str
        ID of the target ZCTA.

    Returns
    -------
    latitude : float
        Latitude of centroid of ZCTA.
    longitude : float
        Target Longitude of centroid of ZCTA.
    """
    valid_zcta_or_raise(zcta)

    conn = metadata_db_connection_proxy.get_connection()
    cur = conn.cursor()

    cur.execute(
        """
      select
        latitude
        , longitude
      from
        zcta_metadata
      where
        zcta_id = ?
    """,
        (zcta,),
    )
    # match existence checked in validate_zcta_or_raise(zcta)
    latitude, longitude = cur.fetchone()

    return float(latitude), float(longitude)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_zcta_ids(state=None):
    conn = metadata_db_connection_proxy.get_connection()
    cur = conn.cursor()

    if state is None:
        cur.execute(
            """
          select zcta_id from zcta_metadata
        """
        )
    else:
        cur.execute(
            """
          select zcta_id from zcta_metadata where state = ?
        """,
            (state,),
        )
    return [row[0] for row in cur.fetchall()]

Response: Returns a list of all supported ZCTAs optionally by state.


Instruction:
Can you write a function in Python 3 where it
checks if ZCTA is valid and raise UnrecognizedZCTAError if not.

Response:
def valid_zcta_or_raise(zcta):
    """ Check if ZCTA is valid and raise eeweather.UnrecognizedZCTAError if not. """
    conn = metadata_db_connection_proxy.get_connection()
    cur = conn.cursor()

    cur.execute(
        """
      select exists (
        select
          zcta_id
        from
          zcta_metadata
        where
          zcta_id = ?
      )
    """,
        (zcta,),
    )
    (exists,) = cur.fetchone()
    if exists:
        return True
    else:
        raise UnrecognizedZCTAError(zcta)


Instruction:
How would you explain what the following Python 3 function does
def valid_usaf_id_or_raise(usaf_id):
    conn = metadata_db_connection_proxy.get_connection()
    cur = conn.cursor()

    cur.execute(
        """
      select exists (
        select
          usaf_id
        from
          isd_station_metadata
        where
          usaf_id = ?
      )
    """,
        (usaf_id,),
    )
    (exists,) = cur.fetchone()
    if exists:
        return True
    else:
        raise UnrecognizedUSAFIDError(usaf_id)

Response: Check if USAF ID is valid and raise UnrecognizedUSAFIDError if not.


Instruction:
Implement a Python 3 function for
returning a ranked version of the candidate weather stations and metadata structures for a particular site.

Response:
def rank_stations(
    site_latitude,
    site_longitude,
    site_state=None,
    site_elevation=None,
    match_iecc_climate_zone=False,
    match_iecc_moisture_regime=False,
    match_ba_climate_zone=False,
    match_ca_climate_zone=False,
    match_state=False,
    minimum_quality=None,
    minimum_tmy3_class=None,
    max_distance_meters=None,
    max_difference_elevation_meters=None,
    is_tmy3=None,
    is_cz2010=None,
):
    """ Get a ranked, filtered set of candidate weather stations and metadata
    for a particular site.

    Parameters
    ----------
    site_latitude : float
        Latitude of target site for which to find candidate weather stations.
    site_longitude : float
        Longitude of target site for which to find candidate weather stations.
    site_state : str, 2 letter abbreviation
        US state of target site, used optionally to filter potential candidate
        weather stations. Ignored unless ``match_state=True``.
    site_elevation : float
        Elevation of target site in meters, used optionally to filter potential
        candidate weather stations. Ignored unless
        ``max_difference_elevation_meters`` is set.
    match_iecc_climate_zone : bool
        If ``True``, filter candidate weather stations to those
        matching the IECC climate zone of the target site.
    match_iecc_moisture_regime : bool
        If ``True``, filter candidate weather stations to those
        matching the IECC moisture regime of the target site.
    match_ca_climate_zone : bool
        If ``True``, filter candidate weather stations to those
        matching the CA climate zone of the target site.
    match_ba_climate_zone : bool
        If ``True``, filter candidate weather stations to those
        matching the Building America climate zone of the target site.
    match_state : bool
        If ``True``, filter candidate weather stations to those
        matching the US state of the target site, as specified by
        ``site_state=True``.
    minimum_quality : str, ``'high'``, ``'medium'``, ``'low'``
        If given, filter candidate weather stations to those meeting or
        exceeding the given quality, as summarized by the frequency and
        availability of observations in the NOAA Integrated Surface Database.
    minimum_tmy3_class : str, ``'I'``, ``'II'``, ``'III'``
        If given, filter candidate weather stations to those meeting or
        exceeding the given class, as reported in the NREL TMY3 metadata.
    max_distance_meters : float
        If given, filter candidate weather stations to those within the
        ``max_distance_meters`` of the target site location.
    max_difference_elevation_meters : float
        If given, filter candidate weather stations to those with elevations
        within ``max_difference_elevation_meters`` of the target site elevation.
    is_tmy3 : bool
        If given, filter candidate weather stations to those for which TMY3
        normal year temperature data is available.
    is_cz2010 : bool
        If given, filter candidate weather stations to those for which CZ2010
        normal year temperature data is available.

    Returns
    -------
    ranked_filtered_candidates : :any:`pandas.DataFrame`
        Index is ``usaf_id``.  Each row contains a potential weather station
        match and metadata. Contains the following columns:

        - ``rank``: Rank of weather station match for the target site.
        - ``distance_meters``: Distance from target site to weather station site.
        - ``latitude``: Latitude of weather station site.
        - ``longitude``: Longitude of weather station site.
        - ``iecc_climate_zone``: IECC Climate Zone ID (1-8)
        - ``iecc_moisture_regime``: IECC Moisture Regime ID (A-C)
        - ``ba_climate_zone``: Building America climate zone name
        - ``ca_climate_zone``: Califoria climate zone number
        - ``rough_quality``: Approximate measure of frequency of ISD
          observations data at weather station.
        - ``elevation``: Elevation of weather station site, if available.
        - ``state``: US state of weather station site, if applicable.
        - ``tmy3_class``: Weather station class as reported by NREL TMY3, if
          available
        - ``is_tmy3``: Weather station has associated TMY3 data.
        - ``is_cz2010``: Weather station has associated CZ2010 data.
        - ``difference_elevation_meters``: Absolute difference in meters
          between target site elevation and weather station elevation, if
          available.

    """
    candidates = cached_data.all_station_metadata

    # compute distances
    candidates_defined_lat_long = candidates[
        candidates.latitude.notnull() & candidates.longitude.notnull()
    ]
    candidates_latitude = candidates_defined_lat_long.latitude
    candidates_longitude = candidates_defined_lat_long.longitude
    tiled_site_latitude = np.tile(site_latitude, candidates_latitude.shape)
    tiled_site_longitude = np.tile(site_longitude, candidates_longitude.shape)
    geod = pyproj.Geod(ellps="WGS84")
    dists = geod.inv(
        tiled_site_longitude,
        tiled_site_latitude,
        candidates_longitude.values,
        candidates_latitude.values,
    )[2]
    distance_meters = pd.Series(dists, index=candidates_defined_lat_long.index).reindex(
        candidates.index
    )
    candidates["distance_meters"] = distance_meters

    if site_elevation is not None:
        difference_elevation_meters = (candidates.elevation - site_elevation).abs()
    else:
        difference_elevation_meters = None
    candidates["difference_elevation_meters"] = difference_elevation_meters

    site_climate_zones = get_lat_long_climate_zones(site_latitude, site_longitude)
    site_iecc_climate_zone = site_climate_zones["iecc_climate_zone"]
    site_iecc_moisture_regime = site_climate_zones["iecc_moisture_regime"]
    site_ca_climate_zone = site_climate_zones["ca_climate_zone"]
    site_ba_climate_zone = site_climate_zones["ba_climate_zone"]

    # create filters
    filters = []

    if match_iecc_climate_zone:
        if site_iecc_climate_zone is None:
            filters.append(candidates.iecc_climate_zone.isnull())
        else:
            filters.append(candidates.iecc_climate_zone == site_iecc_climate_zone)
    if match_iecc_moisture_regime:
        if site_iecc_moisture_regime is None:
            filters.append(candidates.iecc_moisture_regime.isnull())
        else:
            filters.append(candidates.iecc_moisture_regime == site_iecc_moisture_regime)
    if match_ba_climate_zone:
        if site_ba_climate_zone is None:
            filters.append(candidates.ba_climate_zone.isnull())
        else:
            filters.append(candidates.ba_climate_zone == site_ba_climate_zone)
    if match_ca_climate_zone:
        if site_ca_climate_zone is None:
            filters.append(candidates.ca_climate_zone.isnull())
        else:
            filters.append(candidates.ca_climate_zone == site_ca_climate_zone)

    if match_state:
        if site_state is None:
            filters.append(candidates.state.isnull())
        else:
            filters.append(candidates.state == site_state)

    if is_tmy3 is not None:
        filters.append(candidates.is_tmy3.isin([is_tmy3]))
    if is_cz2010 is not None:
        filters.append(candidates.is_cz2010.isin([is_cz2010]))

    if minimum_quality == "low":
        filters.append(candidates.rough_quality.isin(["high", "medium", "low"]))
    elif minimum_quality == "medium":
        filters.append(candidates.rough_quality.isin(["high", "medium"]))
    elif minimum_quality == "high":
        filters.append(candidates.rough_quality.isin(["high"]))

    if minimum_tmy3_class == "III":
        filters.append(candidates.tmy3_class.isin(["I", "II", "III"]))
    elif minimum_tmy3_class == "II":
        filters.append(candidates.tmy3_class.isin(["I", "II"]))
    elif minimum_tmy3_class == "I":
        filters.append(candidates.tmy3_class.isin(["I"]))

    if max_distance_meters is not None:
        filters.append(candidates.distance_meters <= max_distance_meters)

    if max_difference_elevation_meters is not None and site_elevation is not None:
        filters.append(
            candidates.difference_elevation_meters <= max_difference_elevation_meters
        )

    combined_filters = _combine_filters(filters, candidates.index)
    filtered_candidates = candidates[combined_filters]
    ranked_filtered_candidates = filtered_candidates.sort_values(by=["distance_meters"])

    # add rank column
    ranks = range(1, 1 + len(ranked_filtered_candidates))
    ranked_filtered_candidates.insert(0, "rank", ranks)

    return ranked_filtered_candidates[
        [
            "rank",
            "distance_meters",
            "latitude",
            "longitude",
            "iecc_climate_zone",
            "iecc_moisture_regime",
            "ba_climate_zone",
            "ca_climate_zone",
            "rough_quality",
            "elevation",
            "state",
            "tmy3_class",
            "is_tmy3",
            "is_cz2010",
            "difference_elevation_meters",
        ]
    ]


Instruction:
Explain what the following Python 3 code does
def combine_ranked_stations(rankings):

    if len(rankings) == 0:
        raise ValueError("Requires at least one ranking.")

    combined_ranking = rankings[0]
    for ranking in rankings[1:]:
        filtered_ranking = ranking[~ranking.index.isin(combined_ranking.index)]
        combined_ranking = pd.concat([combined_ranking, filtered_ranking])

    combined_ranking["rank"] = range(1, 1 + len(combined_ranking))
    return combined_ranking

Response: Combine the ranked stations into a single hybrid ranking dataframe.


Instruction:
How would you code a function in Python 3 to
select a single station from a list of candidates that meets a given data.

Response:
def select_station(
    candidates,
    coverage_range=None,
    min_fraction_coverage=0.9,
    distance_warnings=(50000, 200000),
    rank=1,
):
    """ Select a station from a list of candidates that meets given data
    quality criteria.

    Parameters
    ----------
    candidates : :any:`pandas.DataFrame`
        A dataframe of the form given by :any:`eeweather.rank_stations` or
        :any:`eeweather.combine_ranked_stations`, specifically having at least
        an index with ``usaf_id`` values and the column ``distance_meters``.

    Returns
    -------
    isd_station, warnings : tuple of (:any:`eeweather.ISDStation`, list of str)
        A qualified weather station. ``None`` if no station meets criteria.
    """

    def _test_station(station):
        if coverage_range is None:
            return True, []
        else:
            start_date, end_date = coverage_range
            try:
                tempC, warnings = eeweather.mockable.load_isd_hourly_temp_data(
                    station, start_date, end_date
                )
            except ISDDataNotAvailableError:
                return False, []  # reject

            # TODO(philngo): also need to incorporate within-day limits
            if len(tempC) > 0:
                fraction_coverage = tempC.notnull().sum() / float(len(tempC))
                return (fraction_coverage > min_fraction_coverage), warnings
            else:
                return False, []  # reject

    def _station_warnings(station, distance_meters):
        return [
            EEWeatherWarning(
                qualified_name="eeweather.exceeds_maximum_distance",
                description=(
                    "Distance from target to weather station is greater"
                    "than the specified km."
                ),
                data={
                    "distance_meters": distance_meters,
                    "max_distance_meters": d,
                    "rank": rank,
                },
            )
            for d in distance_warnings
            if distance_meters > d
        ]

    n_stations_passed = 0
    for usaf_id, row in candidates.iterrows():
        station = ISDStation(usaf_id)
        test_result, warnings = _test_station(station)
        if test_result:
            n_stations_passed += 1
        if n_stations_passed == rank:
            if not warnings:
                warnings = []
            warnings.extend(_station_warnings(station, row.distance_meters))
            return station, warnings

    no_station_warning = EEWeatherWarning(
        qualified_name="eeweather.no_weather_station_selected",
        description=(
            "No weather station found with the specified rank and"
            " minimum fracitional coverage."
        ),
        data={"rank": rank, "min_fraction_coverage": min_fraction_coverage},
    )
    return None, [no_station_warning]


Instruction:
How would you code a function in Python 3 to
load ISD stations metadata from a CSV file.

Response:
def _load_isd_station_metadata(download_path):
    """ Collect metadata for US isd stations.
    """
    from shapely.geometry import Point

    # load ISD history which contains metadata
    isd_history = pd.read_csv(
        os.path.join(download_path, "isd-history.csv"),
        dtype=str,
        parse_dates=["BEGIN", "END"],
    )

    hasGEO = (
        isd_history.LAT.notnull() & isd_history.LON.notnull() & (isd_history.LAT != 0)
    )
    isUS = (
        ((isd_history.CTRY == "US") & (isd_history.STATE.notnull()))
        # AQ = American Samoa, GQ = Guam, RQ = Peurto Rico, VQ = Virgin Islands
        | (isd_history.CTRY.str[1] == "Q")
    )
    hasUSAF = isd_history.USAF != "999999"

    metadata = {}
    for usaf_station, group in isd_history[hasGEO & isUS & hasUSAF].groupby("USAF"):
        # find most recent
        recent = group.loc[group.END.idxmax()]
        wban_stations = list(group.WBAN)
        metadata[usaf_station] = {
            "usaf_id": usaf_station,
            "wban_ids": wban_stations,
            "recent_wban_id": recent.WBAN,
            "name": recent["STATION NAME"],
            "icao_code": recent.ICAO,
            "latitude": recent.LAT if recent.LAT not in ("+00.000",) else None,
            "longitude": recent.LON if recent.LON not in ("+000.000",) else None,
            "point": Point(float(recent.LON), float(recent.LAT)),
            "elevation": recent["ELEV(M)"]
            if not str(float(recent["ELEV(M)"])).startswith("-999")
            else None,
            "state": recent.STATE,
        }

    return metadata


Instruction:
Can you tell what is the following Python 3 function doing
def _load_isd_file_metadata(download_path, isd_station_metadata):

    isd_inventory = pd.read_csv(
        os.path.join(download_path, "isd-inventory.csv"), dtype=str
    )

    # filter to stations with metadata
    station_keep = [usaf in isd_station_metadata for usaf in isd_inventory.USAF]
    isd_inventory = isd_inventory[station_keep]
    # filter by year
    year_keep = isd_inventory.YEAR > "2005"
    isd_inventory = isd_inventory[year_keep]

    metadata = {}
    for (usaf_station, year), group in isd_inventory.groupby(["USAF", "YEAR"]):
        if usaf_station not in metadata:
            metadata[usaf_station] = {"usaf_id": usaf_station, "years": {}}
        metadata[usaf_station]["years"][year] = [
            {
                "wban_id": row.WBAN,
                "counts": [
                    row.JAN,
                    row.FEB,
                    row.MAR,
                    row.APR,
                    row.MAY,
                    row.JUN,
                    row.JUL,
                    row.AUG,
                    row.SEP,
                    row.OCT,
                    row.NOV,
                    row.DEC,
                ],
            }
            for i, row in group.iterrows()
        ]
    return metadata

Response: Load the metadata for the isd files.


Instruction:
Can you create a Python 3 function that
builds the metadata database from primary sources.

Response:
def build_metadata_db(
    zcta_geometry=False,
    iecc_climate_zone_geometry=True,
    iecc_moisture_regime_geometry=True,
    ba_climate_zone_geometry=True,
    ca_climate_zone_geometry=True,
):
    """ Build database of metadata from primary sources.

    Downloads primary sources, clears existing DB, and rebuilds from scratch.

    Parameters
    ----------
    zcta_geometry : bool, optional
        Whether or not to include ZCTA geometry in database.
    iecc_climate_zone_geometry : bool, optional
        Whether or not to include IECC Climate Zone geometry in database.
    iecc_moisture_regime_geometry : bool, optional
        Whether or not to include IECC Moisture Regime geometry in database.
    ba_climate_zone_geometry : bool, optional
        Whether or not to include Building America Climate Zone geometry in database.
    ca_climate_zone_geometry : bool, optional
        Whether or not to include California Building Climate Zone Area geometry in database.
    """

    try:
        import shapely
    except ImportError:
        raise ImportError("Loading polygons requires shapely.")

    try:
        from bs4 import BeautifulSoup
    except ImportError:
        raise ImportError("Scraping TMY3 station data requires beautifulsoup4.")

    try:
        import pyproj
    except ImportError:
        raise ImportError("Computing distances requires pyproj.")

    try:
        import simplejson
    except ImportError:
        raise ImportError("Writing geojson requires simplejson.")

    download_path = _download_primary_sources()
    conn = metadata_db_connection_proxy.reset_database()

    # Load data into memory
    print("Loading ZCTAs")
    zcta_metadata = _load_zcta_metadata(download_path)

    print("Loading counties")
    county_metadata = _load_county_metadata(download_path)

    print("Merging county climate zones")
    (
        iecc_climate_zone_metadata,
        iecc_moisture_regime_metadata,
        ba_climate_zone_metadata,
    ) = _create_merged_climate_zones_metadata(county_metadata)

    print("Loading CA climate zones")
    ca_climate_zone_metadata = _load_CA_climate_zone_metadata(download_path)

    print("Loading ISD station metadata")
    isd_station_metadata = _load_isd_station_metadata(download_path)

    print("Loading ISD station file metadata")
    isd_file_metadata = _load_isd_file_metadata(download_path, isd_station_metadata)

    print("Loading TMY3 station metadata")
    tmy3_station_metadata = _load_tmy3_station_metadata(download_path)

    print("Loading CZ2010 station metadata")
    cz2010_station_metadata = _load_cz2010_station_metadata()

    # Augment data in memory
    print("Computing ISD station quality")
    # add rough station quality to station metadata
    # (all months in last 5 years have at least 600 points)
    _compute_isd_station_quality(isd_station_metadata, isd_file_metadata)

    print("Mapping ZCTAs to climate zones")
    # add county and ca climate zone mappings
    _map_zcta_to_climate_zones(
        zcta_metadata,
        iecc_climate_zone_metadata,
        iecc_moisture_regime_metadata,
        ba_climate_zone_metadata,
        ca_climate_zone_metadata,
    )

    print("Mapping ISD stations to climate zones")
    # add county and ca climate zone mappings
    _map_isd_station_to_climate_zones(
        isd_station_metadata,
        iecc_climate_zone_metadata,
        iecc_moisture_regime_metadata,
        ba_climate_zone_metadata,
        ca_climate_zone_metadata,
    )

    # Write tables
    print("Creating table structures")
    _create_table_structures(conn)

    print("Writing ZCTA data")
    _write_zcta_metadata_table(conn, zcta_metadata, geometry=zcta_geometry)

    print("Writing IECC climate zone data")
    _write_iecc_climate_zone_metadata_table(
        conn, iecc_climate_zone_metadata, geometry=iecc_climate_zone_geometry
    )

    print("Writing IECC moisture regime data")
    _write_iecc_moisture_regime_metadata_table(
        conn, iecc_moisture_regime_metadata, geometry=iecc_moisture_regime_geometry
    )

    print("Writing BA climate zone data")
    _write_ba_climate_zone_metadata_table(
        conn, ba_climate_zone_metadata, geometry=ba_climate_zone_geometry
    )

    print("Writing CA climate zone data")
    _write_ca_climate_zone_metadata_table(
        conn, ca_climate_zone_metadata, geometry=ca_climate_zone_geometry
    )

    print("Writing ISD station metadata")
    _write_isd_station_metadata_table(conn, isd_station_metadata)

    print("Writing ISD file metadata")
    _write_isd_file_metadata_table(conn, isd_file_metadata)

    print("Writing TMY3 station metadata")
    _write_tmy3_station_metadata_table(conn, tmy3_station_metadata)

    print("Writing CZ2010 station metadata")
    _write_cz2010_station_metadata_table(conn, cz2010_station_metadata)

    print("Cleaning up...")
    shutil.rmtree(download_path)

    print("\u2728  Completed! \u2728")


Instruction:
Write a Python 3 script to
return a JSON - serializeable object containing station metadata.

Response:
def json(self):
        """ Return a JSON-serializeable object containing station metadata."""
        return {
            "elevation": self.elevation,
            "latitude": self.latitude,
            "longitude": self.longitude,
            "icao_code": self.icao_code,
            "name": self.name,
            "quality": self.quality,
            "wban_ids": self.wban_ids,
            "recent_wban_id": self.recent_wban_id,
            "climate_zones": {
                "iecc_climate_zone": self.iecc_climate_zone,
                "iecc_moisture_regime": self.iecc_moisture_regime,
                "ba_climate_zone": self.ba_climate_zone,
                "ca_climate_zone": self.ca_climate_zone,
            },
        }


Instruction:
Can you implement a function in Python 3 that
gets filenames of raw ISD station data.

Response:
def get_isd_filenames(self, year=None, with_host=False):
        """ Get filenames of raw ISD station data. """
        return get_isd_filenames(self.usaf_id, year, with_host=with_host)


Instruction:
Write a Python 3 script for
getting filenames of GSOD station data.

Response:
def get_gsod_filenames(self, year=None, with_host=False):
        """ Get filenames of raw GSOD station data. """
        return get_gsod_filenames(self.usaf_id, year, with_host=with_host)