Instruction:
Write a Python 3 script to
check the current state of the experiment to see whether it has been completed.

Response:
def experiment_completed(self):
        """Checks the current state of the experiment to see whether it has
        completed. This makes use of the experiment server `/summary` route,
        which in turn uses :meth:`~Experiment.is_complete`.
        """
        heroku_app = HerokuApp(self.app_id)
        status_url = "{}/summary".format(heroku_app.url)
        data = {}
        try:
            resp = requests.get(status_url)
            data = resp.json()
        except (ValueError, requests.exceptions.RequestException):
            logger.exception("Error fetching experiment status.")
        logger.debug("Current application state: {}".format(data))
        return data.get("completed", False)


Instruction:
Make a summary of the following Python 3 code
def retrieve_data(self):
        local = False
        if self.exp_config.get("mode") == "debug":
            local = True
        filename = export(self.app_id, local=local)
        logger.debug("Data exported to %s" % filename)
        return Data(filename)

Response: Retrieves and saves data from a running experiment


Instruction:
Can you generate a brief explanation for the following Python 3 code
def end_experiment(self):
        if self.exp_config.get("mode") != "debug":
            HerokuApp(self.app_id).destroy()
        return True

Response: Terminates a running experiment


Instruction:
Here you have a function in Python 3, explain what it does
def events_for_replay(self, session=None, target=None):
        if session is None:
            session = self.session
        return session.query(Info).order_by(Info.creation_time)

Response: Returns an ordered list of events for replaying.


Instruction:
How would you code a function in Python 3 to
display Jupyter Notebook widget

Response:
def _ipython_display_(self):
        """Display Jupyter Notebook widget"""
        from IPython.display import display

        self.build_widget()
        display(self.widget())


Instruction:
Can you tell what is the following Python 3 function doing
def from_config(config):
    debug_mode = config.get("mode") == "debug"
    name = config.get("recruiter", None)
    recruiter = None

    # Special case 1: Don't use a configured recruiter in replay mode
    if config.get("replay"):
        return HotAirRecruiter()

    if name is not None:
        recruiter = by_name(name)

        # Special case 2: may run BotRecruiter or MultiRecruiter in any mode
        # (debug or not), so it trumps everything else:
        if isinstance(recruiter, (BotRecruiter, MultiRecruiter)):
            return recruiter

    # Special case 3: if we're not using bots and we're in debug mode,
    # ignore any configured recruiter:
    if debug_mode:
        return HotAirRecruiter()

    # Configured recruiter:
    if recruiter is not None:
        return recruiter

    if name and recruiter is None:
        raise NotImplementedError("No such recruiter {}".format(name))

    # Default if we're not in debug mode:
    return MTurkRecruiter()

Response: Return a Recruiter instance based on the configuration.


Instruction:
Create a Python 3 function to
return initial experiment URL list plus instructions for finding subsequent recruitment events in experiemnt logs.

Response:
def open_recruitment(self, n=1):
        """Return initial experiment URL list, plus instructions
        for finding subsequent recruitment events in experiemnt logs.
        """
        logger.info("Opening CLI recruitment for {} participants".format(n))
        recruitments = self.recruit(n)
        message = (
            'Search for "{}" in the logs for subsequent recruitment URLs.\n'
            "Open the logs for this experiment with "
            '"dallinger logs --app {}"'.format(
                NEW_RECRUIT_LOG_PREFIX, self.config.get("id")
            )
        )
        return {"items": recruitments, "message": message}


Instruction:
Can you create a Python 3 function that
generates experiemnt URLs and print them to the console.

Response:
def recruit(self, n=1):
        """Generate experiemnt URLs and print them to the console."""
        logger.info("Recruiting {} CLI participants".format(n))
        urls = []
        template = "{}/ad?recruiter={}&assignmentId={}&hitId={}&workerId={}&mode={}"
        for i in range(n):
            ad_url = template.format(
                get_base_url(),
                self.nickname,
                generate_random_id(),
                generate_random_id(),
                generate_random_id(),
                self._get_mode(),
            )
            logger.info("{} {}".format(NEW_RECRUIT_LOG_PREFIX, ad_url))
            urls.append(ad_url)

        return urls


Instruction:
Explain what the following Python 3 code does
def reward_bonus(self, assignment_id, amount, reason):
        logger.info(
            'Award ${} for assignment {}, with reason "{}"'.format(
                amount, assignment_id, reason
            )
        )

Response: Print out bonus info for the assignment


Instruction:
Can you write a function in Python 3 where it
returns initial experiment URL list plus instructions for finding subsequent recruitment events in experiemnt logs.

Response:
def open_recruitment(self, n=1):
        """Return initial experiment URL list, plus instructions
        for finding subsequent recruitment events in experiemnt logs.
        """
        logger.info("Opening HotAir recruitment for {} participants".format(n))
        recruitments = self.recruit(n)
        message = "Recruitment requests will open browser windows automatically."

        return {"items": recruitments, "message": message}


Instruction:
Make a summary of the following Python 3 code
def open_recruitment(self, n=1):
        logger.info("Opening Sim recruitment for {} participants".format(n))
        return {"items": self.recruit(n), "message": "Simulated recruitment only"}

Response: Open recruitment for n participants.


Instruction:
How would you explain what the following Python 3 function does
def open_recruitment(self, n=1):
        logger.info("Opening MTurk recruitment for {} participants".format(n))
        if self.is_in_progress:
            raise MTurkRecruiterException(
                "Tried to open_recruitment on already open recruiter."
            )

        if self.hit_domain is None:
            raise MTurkRecruiterException("Can't run a HIT from localhost")

        self.mturkservice.check_credentials()

        if self.config.get("assign_qualifications"):
            self._create_mturk_qualifications()

        hit_request = {
            "max_assignments": n,
            "title": self.config.get("title"),
            "description": self.config.get("description"),
            "keywords": self._config_to_list("keywords"),
            "reward": self.config.get("base_payment"),
            "duration_hours": self.config.get("duration"),
            "lifetime_days": self.config.get("lifetime"),
            "ad_url": self.ad_url,
            "notification_url": self.config.get("notification_url"),
            "approve_requirement": self.config.get("approve_requirement"),
            "us_only": self.config.get("us_only"),
            "blacklist": self._config_to_list("qualification_blacklist"),
            "annotation": self.config.get("id"),
        }
        hit_info = self.mturkservice.create_hit(**hit_request)
        if self.config.get("mode") == "sandbox":
            lookup_url = (
                "https://workersandbox.mturk.com/mturk/preview?groupId={type_id}"
            )
        else:
            lookup_url = "https://worker.mturk.com/mturk/preview?groupId={type_id}"

        return {
            "items": [lookup_url.format(**hit_info)],
            "message": "HIT now published to Amazon Mechanical Turk",
        }

Response: Open a connection to AWS MTurk and create a HIT.


Instruction:
How would you implement a function in Python 3 that
recruits n new participants to an existing HIT

Response:
def recruit(self, n=1):
        """Recruit n new participants to an existing HIT"""
        logger.info("Recruiting {} MTurk participants".format(n))
        if not self.config.get("auto_recruit"):
            logger.info("auto_recruit is False: recruitment suppressed")
            return

        hit_id = self.current_hit_id()
        if hit_id is None:
            logger.info("no HIT in progress: recruitment aborted")
            return

        try:
            return self.mturkservice.extend_hit(
                hit_id, number=n, duration_hours=self.config.get("duration")
            )
        except MTurkServiceException as ex:
            logger.exception(str(ex))


Instruction:
Can you create a Python 3 function that
assigns a Qualification to the Participant for the experiment ID and for the configured group_name.

Response:
def notify_completed(self, participant):
        """Assign a Qualification to the Participant for the experiment ID,
        and for the configured group_name, if it's been set.

        Overrecruited participants don't receive qualifications, since they
        haven't actually completed the experiment. This allows them to remain
        eligible for future runs.
        """
        if participant.status == "overrecruited" or not self.qualification_active:
            return

        worker_id = participant.worker_id

        for name in self.qualifications:
            try:
                self.mturkservice.increment_qualification_score(name, worker_id)
            except QualificationNotFoundException as ex:
                logger.exception(ex)


Instruction:
How would you explain what the following Python 3 function does
def reward_bonus(self, assignment_id, amount, reason):
        try:
            return self.mturkservice.grant_bonus(assignment_id, amount, reason)
        except MTurkServiceException as ex:
            logger.exception(str(ex))

Response: Reward the Turker for a specified assignment with a bonus.


Instruction:
Create a Python 3 function for
creating MTurk Qualification for experiment ID and for group_name .

Response:
def _create_mturk_qualifications(self):
        """Create MTurk Qualification for experiment ID, and for group_name
        if it's been set. Qualifications with these names already exist, but
        it's faster to try and fail than to check, then try.
        """
        for name, desc in self.qualifications.items():
            try:
                self.mturkservice.create_qualification_type(name, desc)
            except DuplicateQualificationNameError:
                pass


Instruction:
Can you write a function in Python 3 where it
starts recruiting right away.

Response:
def open_recruitment(self, n=1):
        """Start recruiting right away."""
        logger.info("Opening Bot recruitment for {} participants".format(n))
        factory = self._get_bot_factory()
        bot_class_name = factory("", "", "").__class__.__name__
        return {
            "items": self.recruit(n),
            "message": "Bot recruitment started using {}".format(bot_class_name),
        }


Instruction:
Implement a Python 3 function for
recruiting n new participant bots to the queue

Response:
def recruit(self, n=1):
        """Recruit n new participant bots to the queue"""
        logger.info("Recruiting {} Bot participants".format(n))
        factory = self._get_bot_factory()
        urls = []
        q = _get_queue()
        for _ in range(n):
            base_url = get_base_url()
            worker = generate_random_id()
            hit = generate_random_id()
            assignment = generate_random_id()
            ad_parameters = (
                "recruiter={}&assignmentId={}&hitId={}&workerId={}&mode=sandbox"
            )
            ad_parameters = ad_parameters.format(self.nickname, assignment, hit, worker)
            url = "{}/ad?{}".format(base_url, ad_parameters)
            urls.append(url)
            bot = factory(url, assignment_id=assignment, worker_id=worker, hit_id=hit)
            job = q.enqueue(bot.run_experiment, timeout=self._timeout)
            logger.warning("Created job {} for url {}.".format(job.id, url))

        return urls


Instruction:
Given the following Python 3 function, write the documentation
def notify_duration_exceeded(self, participants, reference_time):
        for participant in participants:
            participant.status = "rejected"
            session.commit()

Response: Notify the user that the duration of the participants has been exceeded.


Instruction:
Create a Python 3 function for
parsing the specification of how to recruit participants.

Response:
def parse_spec(self):
        """Parse the specification of how to recruit participants.

        Example: recruiters = bots: 5, mturk: 1
        """
        recruiters = []
        spec = get_config().get("recruiters")
        for match in self.SPEC_RE.finditer(spec):
            name = match.group(1)
            count = int(match.group(2))
            recruiters.append((name, count))
        return recruiters


Instruction:
Make a summary of the following Python 3 code
def recruiters(self, n=1):
        recruit_count = 0
        while recruit_count <= n:
            counts = dict(
                session.query(Recruitment.recruiter_id, func.count(Recruitment.id))
                .group_by(Recruitment.recruiter_id)
                .all()
            )
            for recruiter_id, target_count in self.spec:
                remaining = 0
                count = counts.get(recruiter_id, 0)
                if count >= target_count:
                    # This recruiter quota was reached;
                    # move on to the next one.
                    counts[recruiter_id] = count - target_count
                    continue
                else:
                    # Quota is still available; let's use it.
                    remaining = target_count - count
                    break
            else:
                return

            num_recruits = min(n - recruit_count, remaining)
            # record the recruitments and commit
            for i in range(num_recruits):
                session.add(Recruitment(recruiter_id=recruiter_id))
            session.commit()

            recruit_count += num_recruits
            yield by_name(recruiter_id), num_recruits

Response:
Iterator that provides the participant
            count to be recruited for up to n participants.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def open_recruitment(self, n=1):
        logger.info("Multi recruitment running for {} participants".format(n))
        recruitments = []
        messages = {}
        remaining = n
        for recruiter, count in self.recruiters(n):
            if not count:
                break
            if recruiter.nickname in messages:
                result = recruiter.recruit(count)
                recruitments.extend(result)
            else:
                result = recruiter.open_recruitment(count)
                recruitments.extend(result["items"])
                messages[recruiter.nickname] = result["message"]

            remaining -= count
            if remaining <= 0:
                break

        logger.info(
            (
                "Multi-recruited {} out of {} participants, " "using {} recruiters."
            ).format(n - remaining, n, len(messages))
        )

        return {"items": recruitments, "message": "\n".join(messages.values())}

Response: Return initial experiment URL list.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def run_check(participants, config, reference_time):
    recruiters_with_late_participants = defaultdict(list)
    for p in participants:
        timeline = ParticipationTime(p, reference_time, config)
        if timeline.is_overdue:
            print(
                "Error: participant {} with status {} has been playing for too "
                "long - their recruiter will be notified.".format(p.id, p.status)
            )
            recruiters_with_late_participants[p.recruiter_id].append(p)

    for recruiter_id, participants in recruiters_with_late_participants.items():
        recruiter = recruiters.by_name(recruiter_id)
        recruiter.notify_duration_exceeded(participants, reference_time)

Response: Check if the participants have been playing for too long.


Instruction:
How would you explain what the following Python 3 function does
def check_db_for_missing_notifications():
    config = dallinger.config.get_config()
    participants = Participant.query.filter_by(status="working").all()
    reference_time = datetime.now()

    run_check(participants, config, reference_time)

Response: Check the database for missing notifications.


Instruction:
Can you generate the documentation for the following Python 3 function
def _work(self, burst=False, logging_level=logging.INFO):
        setup_loghandlers(logging_level)
        self._install_signal_handlers()

        self.did_perform_work = False
        self.register_birth()
        self.log.info(
            "RQ GEVENT worker (Greenlet pool size={0}) {1!r} started, version {2}".format(
                self.gevent_pool.size, self.key, VERSION
            )
        )
        self.set_state(WorkerStatus.STARTED)

        try:
            while True:
                try:
                    self.check_for_suspension(burst)

                    if self.should_run_maintenance_tasks:
                        self.clean_registries()

                    if self._stop_requested:
                        self.log.info("Stopping on request.")
                        break

                    timeout = None if burst else max(1, self.default_worker_ttl - 60)

                    result = self.dequeue_job_and_maintain_ttl(timeout)
                    if result is None and burst:
                        self.log.info("RQ worker {0!r} done, quitting".format(self.key))

                        try:
                            # Make sure dependented jobs are enqueued.
                            gevent.wait(self.children)
                        except LoopExit:
                            pass
                        result = self.dequeue_job_and_maintain_ttl(timeout)

                    if result is None:
                        break
                except StopRequested:
                    break

                job, queue = result
                self.execute_job(job, queue)

        finally:
            if not self.is_horse:
                self.register_death()
        return self.did_perform_work

Response: Starts the work loop.


Instruction:
Can you write a function in Python 3 where it
spawns a greenlet to be able to kill it when it s blocked dequeueing the job.

Response:
def work(self, burst=False, logging_level=logging.INFO):
        """
        Spawning a greenlet to be able to kill it when it's blocked dequeueing job
        :param burst: if it's burst worker don't need to spawn a greenlet
        """
        # If the is a burst worker it's not needed to spawn greenlet
        if burst:
            return self._work(burst, logging_level=logging_level)

        self.gevent_worker = gevent.spawn(self._work, burst)
        self.gevent_worker.join()
        return self.gevent_worker.value


Instruction:
Explain what the following Python 3 code does
def register(dlgr_id, snapshot=None):
    try:
        config.get("osf_access_token")
    except KeyError:
        pass
    else:
        osf_id = _create_osf_project(dlgr_id)
        _upload_assets_to_OSF(dlgr_id, osf_id)

Response: Register the experiment using configured services.


Instruction:
How would you code a function in Python 3 to
create a project on the OSF.

Response:
def _create_osf_project(dlgr_id, description=None):
    """Create a project on the OSF."""

    if not description:
        description = "Experiment {} registered by Dallinger.".format(dlgr_id)

    r = requests.post(
        "{}/nodes/".format(root),
        data={
            "type": "nodes",
            "category": "project",
            "title": "Experiment dlgr-{}".format(dlgr_id[0:8]),
            "description": description,
        },
        headers={"Authorization": "Bearer {}".format(config.get("osf_access_token"))},
    )
    r.raise_for_status()
    osf_id = r.json()["data"]["id"]

    logger.info("Project registered on OSF at http://osf.io/{}".format(osf_id))

    return osf_id


Instruction:
Make a summary of the following Python 3 code
def _upload_assets_to_OSF(dlgr_id, osf_id, provider="osfstorage"):
    root = "https://files.osf.io/v1"
    snapshot_filename = "{}-code.zip".format(dlgr_id)
    snapshot_path = os.path.join("snapshots", snapshot_filename)
    r = requests.put(
        "{}/resources/{}/providers/{}/".format(root, osf_id, provider),
        params={"kind": "file", "name": snapshot_filename},
        headers={
            "Authorization": "Bearer {}".format(config.get("osf_access_token")),
            "Content-Type": "text/plain",
        },
        data=open(snapshot_path, "rb"),
    )
    r.raise_for_status()

Response: Upload experimental assets to the OSF.


Instruction:
How would you explain what the following Python 3 function does
def outformat_is_json():
    ctx = click.get_current_context()
    state = ctx.ensure_object(CommandState)
    return state.outformat_is_json()

Response: Check if the current click context is json


Instruction:
Create a Python 3 function for
checking if the current click context is Unix.

Response:
def outformat_is_unix():
    """
    Only safe to call within a click context.
    """
    ctx = click.get_current_context()
    state = ctx.ensure_object(CommandState)
    return state.outformat_is_unix()


Instruction:
Make a summary of the following Python 3 code
def outformat_is_text():
    ctx = click.get_current_context()
    state = ctx.ensure_object(CommandState)
    return state.outformat_is_text()

Response: Check if the outformat of the current click context is text.


Instruction:
Create a Python 3 function for
returning the JMESPATH expression for the current click context.

Response:
def get_jmespath_expression():
    """
    Only safe to call within a click context.
    """
    ctx = click.get_current_context()
    state = ctx.ensure_object(CommandState)
    return state.jmespath_expr


Instruction:
Given the following Python 3 function, write the documentation
def verbosity():
    ctx = click.get_current_context()
    state = ctx.ensure_object(CommandState)
    return state.verbosity

Response: Get the current verbosity of the current node.


Instruction:
Make a summary of the following Python 3 code
def is_verbose():
    ctx = click.get_current_context()
    state = ctx.ensure_object(CommandState)
    return state.is_verbose()

Response: Returns True if the current click context is verbose.


Instruction:
How would you explain what the following Python 3 function does
def show_task(successful_transfers, task_id):
    client = get_client()

    if successful_transfers:
        print_successful_transfers(client, task_id)
    else:
        print_task_detail(client, task_id)

Response: Executor for globus task show


Instruction:
How would you explain what the following Python 3 function does
def bookmark_create(endpoint_plus_path, bookmark_name):
    endpoint_id, path = endpoint_plus_path
    client = get_client()

    submit_data = {"endpoint_id": str(endpoint_id), "path": path, "name": bookmark_name}

    res = client.create_bookmark(submit_data)
    formatted_print(res, simple_text="Bookmark ID: {}".format(res["id"]))

Response: Executor for globus bookmark create


Instruction:
Can you tell what is the following Python 3 function doing
def server_list(endpoint_id):
    # raises usage error on shares for us
    endpoint, server_list = get_endpoint_w_server_list(endpoint_id)

    if server_list == "S3":  # not GCS -- this is an S3 endpoint
        server_list = {"s3_url": endpoint["s3_url"]}
        fields = [("S3 URL", "s3_url")]
        text_format = FORMAT_TEXT_RECORD
    else:  # regular GCS host endpoint
        fields = (
            ("ID", "id"),
            ("URI", lambda s: (s["uri"] or "none (Globus Connect Personal)")),
        )
        text_format = FORMAT_TEXT_TABLE
    formatted_print(server_list, text_format=text_format, fields=fields)

Response: Executor for globus endpoint server list


Instruction:
Can you tell what is the following Python 3 function doing
def task_list(
    limit,
    filter_task_id,
    filter_status,
    filter_type,
    filter_label,
    filter_not_label,
    inexact,
    filter_requested_after,
    filter_requested_before,
    filter_completed_after,
    filter_completed_before,
):
    """
    Executor for `globus task-list`
    """

    def _process_filterval(prefix, value, default=None):
        if value:
            if isinstance(value, six.string_types):
                return "{}:{}/".format(prefix, value)
            return "{}:{}/".format(prefix, ",".join(str(x) for x in value))
        else:
            return default or ""

    # make filter string
    filter_string = ""
    filter_string += _process_filterval("task_id", filter_task_id)
    filter_string += _process_filterval("status", filter_status)
    filter_string += _process_filterval(
        "type", filter_type, default="type:TRANSFER,DELETE/"
    )

    # combine data into one list for easier processing
    if inexact:
        label_data = ["~" + s for s in filter_label] + [
            "!~" + s for s in filter_not_label
        ]
    else:
        label_data = ["=" + s for s in filter_label] + [
            "!" + s for s in filter_not_label
        ]
    filter_string += _process_filterval("label", label_data)

    filter_string += _process_filterval(
        "request_time",
        [(filter_requested_after or ""), (filter_requested_before or "")],
    )
    filter_string += _process_filterval(
        "completion_time",
        [(filter_completed_after or ""), (filter_completed_before or "")],
    )

    client = get_client()
    task_iterator = client.task_list(
        num_results=limit, filter=filter_string[:-1]
    )  # ignore trailing /

    fields = [
        ("Task ID", "task_id"),
        ("Status", "status"),
        ("Type", "type"),
        ("Source Display Name", "source_endpoint_display_name"),
        ("Dest Display Name", "destination_endpoint_display_name"),
        ("Label", "label"),
    ]
    formatted_print(
        task_iterator, fields=fields, json_converter=iterable_response_to_dict
    )

Response: Executor for globus task - list


Instruction:
Given the following Python 3 function, write the documentation
def delete_command(
    batch,
    ignore_missing,
    star_silent,
    recursive,
    enable_globs,
    endpoint_plus_path,
    label,
    submission_id,
    dry_run,
    deadline,
    skip_activation_check,
    notify,
):
    """
    Executor for `globus delete`
    """
    endpoint_id, path = endpoint_plus_path
    if path is None and (not batch):
        raise click.UsageError("delete requires either a PATH OR --batch")

    client = get_client()

    # attempt to activate unless --skip-activation-check is given
    if not skip_activation_check:
        autoactivate(client, endpoint_id, if_expires_in=60)

    delete_data = DeleteData(
        client,
        endpoint_id,
        label=label,
        recursive=recursive,
        ignore_missing=ignore_missing,
        submission_id=submission_id,
        deadline=deadline,
        skip_activation_check=skip_activation_check,
        interpret_globs=enable_globs,
        **notify
    )

    if batch:
        # although this sophisticated structure (like that in transfer)
        # isn't strictly necessary, it gives us the ability to add options in
        # the future to these lines with trivial modifications
        @click.command()
        @click.argument("path", type=TaskPath(base_dir=path))
        def process_batch_line(path):
            """
            Parse a line of batch input and add it to the delete submission
            item.
            """
            delete_data.add_item(str(path))

        shlex_process_stdin(process_batch_line, "Enter paths to delete, line by line.")
    else:
        if not star_silent and enable_globs and path.endswith("*"):
            # not intuitive, but `click.confirm(abort=True)` prints to stdout
            # unnecessarily, which we don't really want...
            # only do this check if stderr is a pty
            if (
                err_is_terminal()
                and term_is_interactive()
                and not click.confirm(
                    'Are you sure you want to delete all files matching "{}"?'.format(
                        path
                    ),
                    err=True,
                )
            ):
                safeprint("Aborted.", write_to_stderr=True)
                click.get_current_context().exit(1)
        delete_data.add_item(path)

    if dry_run:
        formatted_print(delete_data, response_key="DATA", fields=[("Path", "path")])
        # exit safely
        return

    res = client.submit_delete(delete_data)
    formatted_print(
        res,
        text_format=FORMAT_TEXT_RECORD,
        fields=(("Message", "message"), ("Task ID", "task_id")),
    )

Response: Executor for globus delete


Instruction:
Can you generate a brief explanation for the following Python 3 code
def set_command(value, parameter):
    conf = get_config_obj()

    section = "cli"
    if "." in parameter:
        section, parameter = parameter.split(".", 1)

    # ensure that the section exists
    if section not in conf:
        conf[section] = {}
    # set the value for the given parameter
    conf[section][parameter] = value

    # write to disk
    safeprint("Writing updated config to {}".format(conf.filename))
    conf.write()

Response: Executor for globus config set


Instruction:
Can you write a function in Python 3 where it
processes the stdin line by line.

Response:
def shlex_process_stdin(process_command, helptext):
    """
    Use shlex to process stdin line-by-line.
    Also prints help text.

    Requires that @process_command be a Click command object, used for
    processing single lines of input. helptext is prepended to the standard
    message printed to interactive sessions.
    """
    # if input is interactive, print help to stderr
    if sys.stdin.isatty():
        safeprint(
            (
                "{}\n".format(helptext) + "Lines are split with shlex in POSIX mode: "
                "https://docs.python.org/library/shlex.html#parsing-rules\n"
                "Terminate input with Ctrl+D or <EOF>\n"
            ),
            write_to_stderr=True,
        )

    # use readlines() rather than implicit file read line looping to force
    # python to properly capture EOF (otherwise, EOF acts as a flush and
    # things get weird)
    for line in sys.stdin.readlines():
        # get the argument vector:
        # do a shlex split to handle quoted paths with spaces in them
        # also lets us have comments with #
        argv = shlex.split(line, comments=True)
        if argv:
            try:
                process_command.main(args=argv)
            except SystemExit as e:
                if e.code != 0:
                    raise


Instruction:
Explain what the following Python 3 code does
def globus_group(*args, **kwargs):

    def inner_decorator(f):
        f = click.group(*args, cls=GlobusCommandGroup, **kwargs)(f)
        f = common_options(f)
        return f

    return inner_decorator

Response: Decorator for globus group


Instruction:
Here you have a function in Python 3, explain what it does
def _get_package_data():
    moddata = []
    modlist = (
        "click",
        "configobj",
        "cryptography",
        "globus_cli",
        "globus_sdk",
        "jmespath",
        "requests",
        "six",
    )
    if verbosity() < 2:
        modlist = ("globus_cli", "globus_sdk", "requests")

    for mod in modlist:
        cur = [mod]
        try:
            loaded_mod = __import__(mod)
        except ImportError:
            loaded_mod = None

        for attr in ("__version__", "__file__", "__path__"):
            # if loading failed, be sure to pad with error messages
            if loaded_mod is None:
                cur.append("[import failed]")
                continue

            try:
                attrval = getattr(loaded_mod, attr)
            except AttributeError:
                attrval = ""
            cur.append(attrval)
        moddata.append(cur)

    return moddata

Response:
Imports a set of important packages and returns relevant data about them in a
    dict.


Instruction:
Given the following Python 3 function, write the documentation
def print_version():
    latest, current = get_versions()
    if latest is None:
        safeprint(
            ("Installed Version: {0}\n" "Failed to lookup latest version.").format(
                current
            )
        )
    else:
        safeprint(
            ("Installed Version: {0}\n" "Latest Version:    {1}\n" "\n{2}").format(
                current,
                latest,
                "You are running the latest version of the Globus CLI"
                if current == latest
                else (
                    "You should update your version of the Globus CLI with\n"
                    "  globus update"
                )
                if current < latest
                else "You are running a preview version of the Globus CLI",
            )
        )

    # verbose shows more platform and python info
    # it also includes versions of some CLI dependencies
    if is_verbose():
        moddata = _get_package_data()

        safeprint("\nVerbose Data\n---")

        safeprint("platform:")
        safeprint("  platform: {}".format(platform.platform()))
        safeprint("  py_implementation: {}".format(platform.python_implementation()))
        safeprint("  py_version: {}".format(platform.python_version()))
        safeprint("  sys.executable: {}".format(sys.executable))
        safeprint("  site.USER_BASE: {}".format(site.USER_BASE))

        safeprint("modules:")
        for mod, modversion, modfile, modpath in moddata:
            safeprint("  {}:".format(mod))
            safeprint("    __version__: {}".format(modversion))
            safeprint("    __file__: {}".format(modfile))
            safeprint("    __path__: {}".format(modpath))

Response: Print out the current version of the Globus CLI.


Instruction:
Write a Python 3 function that can
invoke pip and print the output.

Response:
def _call_pip(*args):
    """
    Invoke pip *safely* and in the *supported* way:
    https://pip.pypa.io/en/latest/user_guide/#using-pip-from-your-program
    """
    all_args = [sys.executable, "-m", "pip"] + list(args)
    print("> {}".format(" ".join(all_args)))
    subprocess.check_call(all_args)


Instruction:
Explain what the following Python 3 code does
def _check_pip_installed():
    try:
        subprocess.check_output(
            [sys.executable, "-m", "pip", "--version"], stderr=subprocess.STDOUT
        )
        return True
    except subprocess.CalledProcessError:
        return False

Response: Check if pip is installed and return True if it is installed False otherwise.


Instruction:
Here you have a function in Python 3, explain what it does
def update_command(yes, development, development_version):
    # enforce that pip MUST be installed
    # Why not just include it in the setup.py requirements? Mostly weak
    # reasons, but it shouldn't matter much.
    # - if someone has installed the CLI without pip, then they haven't
    #   followed our install instructions, so it's mostly a non-issue
    # - we don't want to have `pip install -U globus-cli` upgrade pip -- that's
    #   a little bit invasive and easy to do by accident on modern versions of
    #   pip where `--upgrade-strategy` defaults to `eager`
    # - we may want to do distributions in the future with dependencies baked
    #   into a package, but we'd never want to do that with pip. More changes
    #   would be needed to support that use-case, which we've discussed, but
    #   not depending directly on pip gives us a better escape hatch
    # - if we depend on pip, we need to start thinking about what versions we
    #   support. In point of fact, that becomes an issue as soon as we add this
    #   command, but not being explicit about it lets us punt for now (maybe
    #   indefinitely) on figuring out version requirements. All of that is to
    #   say: not including it is bad, and from that badness we reap the rewards
    #   of procrastination and non-explicit requirements
    # - Advanced usage, like `pip install -t` can produce an installed version
    #   of the CLI which can't import its installing `pip`. If we depend on
    #   pip, anyone doing this is forced to get two copies of pip, which seems
    #   kind of nasty (even if "they're asking for it")
    if not _check_pip_installed():
        safeprint("`globus update` requires pip. " "Please install pip and try again")
        click.get_current_context().exit(1)

    # --development-version implies --development
    development = development or (development_version is not None)

    # if we're running with `--development`, then the target version is a
    # tarball from GitHub, and we can skip out on the safety checks
    if development:
        # default to master
        development_version = development_version or "master"
        target_version = (
            "https://github.com/globus/globus-cli/archive/{}" ".tar.gz#egg=globus-cli"
        ).format(development_version)
    else:
        # lookup version from PyPi, abort if we can't get it
        latest, current = get_versions()
        if latest is None:
            safeprint("Failed to lookup latest version. Aborting.")
            click.get_current_context().exit(1)

        # in the case where we're already up to date, do nothing and exit
        if current == latest:
            safeprint("You are already running the latest version: {}".format(current))
            return

        # if we're up to date (or ahead, meaning a dev version was installed)
        # then prompt before continuing, respecting `--yes`
        else:
            safeprint(
                (
                    "You are already running version {0}\n"
                    "The latest version is           {1}"
                ).format(current, latest)
            )
            if not yes and (
                not click.confirm("Continue with the upgrade?", default=True)
            ):
                click.get_current_context().exit(1)

        # if we make it through to here, it means we didn't hit any safe (or
        # unsafe) abort conditions, so set the target version for upgrade to
        # the latest
        target_version = "globus-cli=={}".format(latest)

    # print verbose warning/help message, to guide less fortunate souls who hit
    # Ctrl+C at a foolish time, lose connectivity, or don't invoke with `sudo`
    # on a global install of the CLI
    safeprint(
        (
            "The Globus CLI will now update itself.\n"
            "In the event that an error occurs or the update is interrupted, we "
            "recommend uninstalling and reinstalling the CLI.\n"
            "Update Target: {}\n"
        ).format(target_version)
    )

    # register the upgrade activity as an atexit function
    # this ensures that most library teardown (other than whatever libs might
    # jam into atexit themselves...) has already run, and therefore protects us
    # against most potential bugs resulting from upgrading click while a click
    # command is running
    #
    # NOTE: there is a risk that we will see bugs on upgrade if the act of
    # doing a pip upgrade install changes state on disk and we (or a lib we
    # use) rely on that via pkg_resources, lazy/deferred imports, or good
    # old-fashioned direct inspection of `__file__` and the like DURING an
    # atexit method. Anything outside of atexit methods remains safe!
    @atexit.register
    def do_upgrade():
        install_args = ["install", "--upgrade", target_version]
        if IS_USER_INSTALL:
            install_args.insert(1, "--user")
        _call_pip(*install_args)

Response: Executor for globus update


Instruction:
Explain what the following Python 3 code does
def whoami_command(linked_identities):
    client = get_auth_client()

    # get userinfo from auth.
    # if we get back an error the user likely needs to log in again
    try:
        res = client.oauth2_userinfo()
    except AuthAPIError:
        safeprint(
            "Unable to get user information. Please try " "logging in again.",
            write_to_stderr=True,
        )
        click.get_current_context().exit(1)

    print_command_hint(
        "For information on which identities are in session see\n"
        "  globus session show\n"
    )

    # --linked-identities either displays all usernames or a table if verbose
    if linked_identities:
        try:
            formatted_print(
                res["identity_set"],
                fields=[
                    ("Username", "username"),
                    ("Name", "name"),
                    ("ID", "sub"),
                    ("Email", "email"),
                ],
                simple_text=(
                    None
                    if is_verbose()
                    else "\n".join([x["username"] for x in res["identity_set"]])
                ),
            )
        except KeyError:
            safeprint(
                "Your current login does not have the consents required "
                "to view your full identity set. Please log in again "
                "to agree to the required consents.",
                write_to_stderr=True,
            )

    # Default output is the top level data
    else:
        formatted_print(
            res,
            text_format=FORMAT_TEXT_RECORD,
            fields=[
                ("Username", "preferred_username"),
                ("Name", "name"),
                ("ID", "sub"),
                ("Email", "email"),
            ],
            simple_text=(None if is_verbose() else res["preferred_username"]),
        )

Response: Executor for globus whoami


Instruction:
Can you write a function in Python 3 where it
walks the tree of commands to a terminal command or multicommand and returns a new context object that can be used to perform completion work on that command.

Response:
def get_completion_context(args):
    """
    Walk the tree of commands to a terminal command or multicommand, using the
    Click Context system.
    Effectively, we'll be using the resilient_parsing mode of commands to stop
    evaluation, then having them capture their options and arguments, passing
    us on to the next subcommand. If we walk "off the tree" with a command that
    we don't recognize, we have a hardstop condition, but otherwise, we walk as
    far as we can go and that's the location from which we should do our
    completion work.
    """
    # get the "globus" command as a click.Command
    root_command = click.get_current_context().find_root().command
    # build a new context object off of it, with resilient_parsing set so that
    # no callbacks are invoked
    ctx = root_command.make_context("globus", list(args), resilient_parsing=True)

    # walk down multicommands until we've matched on everything and are at a
    # terminal context that holds all of our completed args
    while isinstance(ctx.command, click.MultiCommand) and args:
        # trim out any params that are capturable at this level of the command
        # tree by resetting the argument list
        args = ctx.protected_args + ctx.args

        # if there were no remaining args, stop walking the tree
        if not args:
            break

        # check for a matching command, and if one isn't found stop the
        # traversal and abort the whole process -- this would mean that a
        # completed command was entered which doesn't match a known command
        # there's nothing completion can do in this case unless it implements
        # sophisticated fuzzy matching
        command = ctx.command.get_command(ctx, args[0])
        if not command:
            return None

        # otherwise, grab that command, and build a subcontext to continue the
        # tree walk
        else:
            ctx = command.make_context(
                args[0], args[1:], parent=ctx, resilient_parsing=True
            )

    # return the context we found
    return ctx


Instruction:
Here you have a function in Python 3, explain what it does
def get_all_choices(completed_args, cur, quoted):
    ctx = get_completion_context(completed_args)
    if not ctx:
        return []

    # matching rules, so we can toggle by type and such
    def match_with_case(n, m):
        """case matters"""
        return n.startswith(m)

    def match_nocase(n, m):
        """case doesn't matter"""
        return n.lower().startswith(m.lower())

    match_func = match_with_case

    ctx_options = [
        p for p in ctx.command.get_params(ctx) if isinstance(p, click.Option)
    ]

    last_completed = None
    if completed_args:
        last_completed = completed_args[-1]

    # if the last completed argument matches a Choice option, we're going to
    # have to expand cur as a choice param
    matching_choice_opt = None
    for p in ctx_options:
        if isinstance(p.type, click.Choice) and last_completed in p.opts:
            matching_choice_opt = p

    choices = []
    # if we ended on a choice, complete with all of the available values
    if matching_choice_opt:
        # catch the case where it's case insensitive, and we need to change our
        # comparisons / matching later on
        if isinstance(matching_choice_opt.type, CaseInsensitiveChoice):
            match_func = match_nocase
        choices = [
            (x, matching_choice_opt.help) for x in matching_choice_opt.type.choices
        ]
    # if cur looks like an option, just look for options
    # but skip if it's quoted text
    elif cur and cur.startswith("-") and not quoted:
        for param in ctx_options:
            # skip hidden options
            if isinstance(param, HiddenOption):
                continue
            for optset in (param.opts, param.secondary_opts):
                for opt in optset:
                    # only add long-opts, never short opts to completion,
                    # unless the cur appears to be a short opt already
                    if opt.startswith("--") or (len(cur) > 1 and cur[1] != "-"):
                        choices.append((opt, param.help))
    # and if it's a multicommand we see, get the list of subcommands
    elif isinstance(ctx.command, click.MultiCommand) and not quoted:
        choices = [
            (cmdname, ctx.command.get_command(ctx, cmdname).short_help)
            for cmdname in ctx.command.list_commands(ctx)
        ]
    else:
        pass

    # now, do final filtering
    if cur:
        choices = [(n, h) for (n, h) in choices if match_func(n, cur)]

    return choices

Response: This function returns all available choices for the current word in progress.


Instruction:
Here you have a function in Python 3, explain what it does
def endpoint_is_activated(endpoint_id, until, absolute_time):
    client = get_client()
    res = client.endpoint_get_activation_requirements(endpoint_id)

    def fail(deadline=None):
        exp_string = ""
        if deadline is not None:
            exp_string = " or will expire within {} seconds".format(deadline)

        message = "The endpoint is not activated{}.\n\n".format(
            exp_string
        ) + activation_requirements_help_text(res, endpoint_id)
        formatted_print(res, simple_text=message)
        click.get_current_context().exit(1)

    def success(msg, *format_params):
        formatted_print(res, simple_text=(msg.format(endpoint_id, *format_params)))
        click.get_current_context().exit(0)

    # eternally active endpoints have a special expires_in value
    if res["expires_in"] == -1:
        success("{} does not require activation")

    # autoactivation is not supported and --until was not passed
    if until is None:
        # and we are active right now (0s in the future)...
        if res.active_until(0):
            success("{} is activated")
        # or we are not active
        fail()

    # autoactivation is not supported and --until was passed
    if res.active_until(until, relative_time=not absolute_time):
        success("{} will be active for at least {} seconds", until)
    else:
        fail(deadline=until)

Response: Executor for globus endpoint is - activated


Instruction:
How would you explain what the following Python 3 function does
def endpoint_create(**kwargs):
    client = get_client()

    # get endpoint type, ensure unambiguous.
    personal = kwargs.pop("personal")
    server = kwargs.pop("server")
    shared = kwargs.pop("shared")

    if personal and (not server) and (not shared):
        endpoint_type = "personal"
    elif server and (not personal) and (not shared):
        endpoint_type = "server"
    elif shared and (not personal) and (not server):
        endpoint_type = "shared"
    else:
        raise click.UsageError(
            "Exactly one of --personal, --server, or --shared is required."
        )

    # validate options
    kwargs["is_globus_connect"] = personal or None
    validate_endpoint_create_and_update_params(endpoint_type, False, kwargs)

    # shared endpoint creation
    if shared:
        endpoint_id, host_path = shared
        kwargs["host_endpoint"] = endpoint_id
        kwargs["host_path"] = host_path

        ep_doc = assemble_generic_doc("shared_endpoint", **kwargs)
        autoactivate(client, endpoint_id, if_expires_in=60)
        res = client.create_shared_endpoint(ep_doc)

    # non shared endpoint creation
    else:
        # omit `is_globus_connect` key if not GCP, otherwise include as `True`
        ep_doc = assemble_generic_doc("endpoint", **kwargs)
        res = client.create_endpoint(ep_doc)

    # output
    formatted_print(
        res,
        fields=(COMMON_FIELDS + GCP_FIELDS if personal else COMMON_FIELDS),
        text_format=FORMAT_TEXT_RECORD,
    )

Response: Executor for globus endpoint create


Instruction:
Can you generate a brief explanation for the following Python 3 code
def server_update(
    endpoint_id,
    server_id,
    subject,
    port,
    scheme,
    hostname,
    incoming_data_ports,
    outgoing_data_ports,
):
    """
    Executor for `globus endpoint server update`
    """
    client = get_client()

    server_doc = assemble_generic_doc(
        "server", subject=subject, port=port, scheme=scheme, hostname=hostname
    )

    # n.b. must be done after assemble_generic_doc(), as that function filters
    # out `None`s, which we need to be able to set for `'unspecified'`
    if incoming_data_ports:
        server_doc.update(
            incoming_data_port_start=incoming_data_ports[0],
            incoming_data_port_end=incoming_data_ports[1],
        )
    if outgoing_data_ports:
        server_doc.update(
            outgoing_data_port_start=outgoing_data_ports[0],
            outgoing_data_port_end=outgoing_data_ports[1],
        )

    res = client.update_endpoint_server(endpoint_id, server_id, server_doc)
    formatted_print(res, text_format=FORMAT_TEXT_RAW, response_key="message")

Response: Executor for globus endpoint server update


Instruction:
How would you code a function in Python 3 to
try to decode a b32 - encoded username.

Response:
def _try_b32_decode(v):
    """
    Attempt to decode a b32-encoded username which is sometimes generated by
    internal Globus components.

    The expectation is that the string is a valid ID, username, or b32-encoded
    name. Therefore, we can do some simple checking on it.

    If it does not appear to be formatted correctly, return None.
    """
    # should start with "u_"
    if not v.startswith("u_"):
        return None
    # usernames have @ , we want to allow `u_foo@example.com`
    # b32 names never have @
    if "@" in v:
        return None
    # trim "u_"
    v = v[2:]
    # wrong length
    if len(v) != 26:
        return None

    # append padding and uppercase so that b32decode will work
    v = v.upper() + (6 * "=")

    # try to decode
    try:
        return str(uuid.UUID(bytes=base64.b32decode(v)))
    # if it fails, I guess it's a username? Not much left to do
    except ValueError:
        return None


Instruction:
Explain what the following Python 3 code does
def supported_activation_methods(res):
    supported = ["web"]  # web activation is always supported.

    # oauth
    if res["oauth_server"]:
        supported.append("oauth")

    for req in res["DATA"]:
        # myproxy
        if (
            req["type"] == "myproxy"
            and req["name"] == "hostname"
            and req["value"] != "myproxy.globusonline.org"
        ):
            supported.append("myproxy")

        # delegate_proxy
        if req["type"] == "delegate_proxy" and req["name"] == "public_key":
            supported.append("delegate_proxy")

    return supported

Response: Given an activation_requirements document returns a list of activation methods supported by this endpoint.


Instruction:
Implement a function in Python 3 to
give an activation requirements document and an endpoint_id returns a string of help text for how to activate the endpoint

Response:
def activation_requirements_help_text(res, ep_id):
    """
    Given an activation requirements document and an endpoint_id
    returns a string of help text for how to activate the endpoint
    """
    methods = supported_activation_methods(res)

    lines = [
        "This endpoint supports the following activation methods: ",
        ", ".join(methods).replace("_", " "),
        "\n",
        (
            "For web activation use:\n"
            "'globus endpoint activate --web {}'\n".format(ep_id)
            if "web" in methods
            else ""
        ),
        (
            "For myproxy activation use:\n"
            "'globus endpoint activate --myproxy {}'\n".format(ep_id)
            if "myproxy" in methods
            else ""
        ),
        (
            "For oauth activation use web activation:\n"
            "'globus endpoint activate --web {}'\n".format(ep_id)
            if "oauth" in methods
            else ""
        ),
        (
            "For delegate proxy activation use:\n"
            "'globus endpoint activate --delegate-proxy "
            "X.509_PEM_FILE {}'\n".format(ep_id)
            if "delegate_proxy" in methods
            else ""
        ),
        (
            "Delegate proxy activation requires an additional dependency on "
            "cryptography. See the docs for details:\n"
            "https://docs.globus.org/cli/reference/endpoint_activate/\n"
            if "delegate_proxy" in methods
            else ""
        ),
    ]

    return "".join(lines)


Instruction:
Write a Python 3 script for
attempting to auto - activate the given endpoint with the given client

Response:
def autoactivate(client, endpoint_id, if_expires_in=None):
    """
    Attempts to auto-activate the given endpoint with the given client
    If auto-activation fails, parses the returned activation requirements
    to determine which methods of activation are supported, then tells
    the user to use 'globus endpoint activate' with the correct options(s)
    """
    kwargs = {}
    if if_expires_in is not None:
        kwargs["if_expires_in"] = if_expires_in

    res = client.endpoint_autoactivate(endpoint_id, **kwargs)
    if res["code"] == "AutoActivationFailed":

        message = (
            "The endpoint could not be auto-activated and must be "
            "activated before it can be used.\n\n"
            + activation_requirements_help_text(res, endpoint_id)
        )

        safeprint(message, write_to_stderr=True)
        click.get_current_context().exit(1)

    else:
        return res


Instruction:
Can you write a function in Python 3 where it
returns a list of server list for the given endpoint.

Response:
def get_endpoint_w_server_list(endpoint_id):
    """
    A helper for handling endpoint server list lookups correctly accounting
    for various endpoint types.

    - Raises click.UsageError when used on Shares
    - Returns (<get_endpoint_response>, "S3") for S3 endpoints
    - Returns (<get_endpoint_response>, <server_list_response>) for all other
      Endpoints
    """
    client = get_client()

    endpoint = client.get_endpoint(endpoint_id)

    if endpoint["host_endpoint_id"]:  # not GCS -- this is a share endpoint
        raise click.UsageError(
            dedent(
                u"""\
            {id} ({0}) is a share and does not have servers.

            To see details of the share, use
                globus endpoint show {id}

            To list the servers on the share's host endpoint, use
                globus endpoint server list {host_endpoint_id}
        """
            ).format(display_name_or_cname(endpoint), **endpoint.data)
        )

    if endpoint["s3_url"]:  # not GCS -- legacy S3 endpoint type
        return (endpoint, "S3")

    else:
        return (endpoint, client.endpoint_server_list(endpoint_id))


Instruction:
Can you implement a function in Python 3 that
options are the core "task wait" options, including the `--meow` easter egg. This does the core "task wait" loop, including all of the IO. It *does exit* on behalf of the caller. (We can enhance with a `noabort=True` param or somesuch in the future if necessary.)

Response:
def task_wait_with_io(
    meow, heartbeat, polling_interval, timeout, task_id, timeout_exit_code, client=None
):
    """
    Options are the core "task wait" options, including the `--meow` easter
    egg.

    This does the core "task wait" loop, including all of the IO.
    It *does exit* on behalf of the caller. (We can enhance with a
    `noabort=True` param or somesuch in the future if necessary.)
    """
    client = client or get_client()

    def timed_out(waited_time):
        if timeout is None:
            return False
        else:
            return waited_time >= timeout

    def check_completed():
        completed = client.task_wait(
            task_id, timeout=polling_interval, polling_interval=polling_interval
        )
        if completed:
            if heartbeat:
                safeprint("", write_to_stderr=True)
            # meowing tasks wake up!
            if meow:
                safeprint(
                    r"""
                  _..
  /}_{\           /.-'
 ( a a )-.___...-'/
 ==._.==         ;
      \ i _..._ /,
      {_;/   {_//""",
                    write_to_stderr=True,
                )

            # TODO: possibly update TransferClient.task_wait so that we don't
            # need to do an extra fetch to get the task status after completion
            res = client.get_task(task_id)
            formatted_print(res, text_format=FORMAT_SILENT)

            status = res["status"]
            if status == "SUCCEEDED":
                click.get_current_context().exit(0)
            else:
                click.get_current_context().exit(1)

        return completed

    # Tasks start out sleepy
    if meow:
        safeprint(
            r"""
   |\      _,,,---,,_
   /,`.-'`'    -.  ;-;;,_
  |,4-  ) )-,_..;\ (  `'-'
 '---''(_/--'  `-'\_)""",
            write_to_stderr=True,
        )

    waited_time = 0
    while not timed_out(waited_time) and not check_completed():
        if heartbeat:
            safeprint(".", write_to_stderr=True, newline=False)
            sys.stderr.flush()

        waited_time += polling_interval

    # add a trailing newline to heartbeats if we fail
    if heartbeat:
        safeprint("", write_to_stderr=True)

    exit_code = 1
    if timed_out(waited_time):
        safeprint(
            "Task has yet to complete after {} seconds".format(timeout),
            write_to_stderr=True,
        )
        exit_code = timeout_exit_code

    # output json if requested, but nothing for text mode
    res = client.get_task(task_id)
    formatted_print(res, text_format=FORMAT_SILENT)

    click.get_current_context().exit(exit_code)


Instruction:
Write a Python 3 function that can
try the given function f with the given arguments and kwargs.

Response:
def retry(self, f, *args, **kwargs):
        """
        Retries the given function self.tries times on NetworkErros
        """
        backoff = random.random() / 100  # 5ms on average
        for _ in range(self.tries - 1):
            try:
                return f(*args, **kwargs)
            except NetworkError:
                time.sleep(backoff)
                backoff *= 2
        return f(*args, **kwargs)


Instruction:
Here you have a function in Python 3, explain what it does
def recursive_operation_ls(
        self, endpoint_id, depth=3, filter_after_first=True, **params
    ):
        """
        Makes recursive calls to ``GET /operation/endpoint/<endpoint_id>/ls``
        Does not preserve access to top level operation_ls fields, but
        adds a "path" field for every item that represents the full
        path to that item.
        :rtype: iterable of :class:`GlobusResponse
                <globus_sdk.response.GlobusResponse>`
        **Parameters**
            ``endpoint_id`` (*string*)
              The endpoint being recursively ls'ed. If no "path" is given in
              params, the start path is determined by this endpoint.
            ``depth`` (*int*)
              The maximum file depth the recursive ls will go to.
            ``filter_after_first`` (*bool*)
              If False, any "filter" in params will only be applied to the
              first, top level ls, all results beyond that will be unfiltered.
            ``params``
              Parameters that will be passed through as query params.
        **Examples**
        >>> tc = globus_sdk.TransferClient(...)
        >>> for entry in tc.recursive_operation_ls(ep_id, path="/~/project1/"):
        >>>     print(entry["path"], entry["type"])
        **External Documentation**
        See
        `List Directory Contents \
        <https://docs.globus.org/api/transfer/file_operations/#list_directory_contents>`_
        in the REST documentation for details, but note that top level data
        fields are no longer available and an additional per item
        "path" field is added.
        """
        endpoint_id = safe_stringify(endpoint_id)
        self.logger.info(
            "TransferClient.recursive_operation_ls({}, {}, {})".format(
                endpoint_id, depth, params
            )
        )
        return RecursiveLsResponse(self, endpoint_id, depth, filter_after_first, params)

Response: This method is used to recursively ls the directory contents of a file.


Instruction:
Can you tell what is the following Python 3 function doing
def convert(self, value, param, ctx):
        # passthrough conditions: None or already processed
        if value is None or isinstance(value, tuple):
            return value

        # split the value on the first colon, leave the rest intact
        splitval = value.split(":", 1)
        # first element is the endpoint_id
        endpoint_id = click.UUID(splitval[0])

        # get the second element, defaulting to `None` if there was no colon in
        # the original value
        try:
            path = splitval[1]
        except IndexError:
            path = None
        # coerce path="" to path=None
        # means that we treat "enpdoint_id" and "endpoint_id:" equivalently
        path = path or None

        if path is None and self.path_required:
            self.fail("The path component is required", param=param)

        return (endpoint_id, path)

Response: Convert a value to a tuple.


Instruction:
Given the following Python 3 function, write the documentation
def one_use_option(*args, **kwargs):
    # cannot force a multiple or count option to be single use
    if "multiple" in kwargs or "count" in kwargs:
        raise ValueError(
            "Internal error, one_use_option cannot be  used " "with multiple or count."
        )

    # cannot force a non Option Paramater (argument) to be a OneUseOption
    if kwargs.get("cls"):
        raise TypeError(
            "Internal error, one_use_option cannot overwrite "
            "cls {}.".format(kwargs.get("cls"))
        )

    # use our OneUseOption class instead of a normal Option
    kwargs["cls"] = OneUseOption

    # if dealing with a flag, switch to a counting option,
    # and then assert if the count is not greater than 1 and cast to a bool
    if kwargs.get("is_flag"):
        kwargs["is_flag"] = False  # mutually exclusive with count
        kwargs["count"] = True

    # if not a flag, this option takes an argument(s), switch to a multiple
    # option, assert the len is 1, and treat the first element as the value
    else:
        kwargs["multiple"] = True

    # decorate with the click.option decorator, but with our custom kwargs
    def decorator(f):
        return click.option(*args, **kwargs)(f)

    return decorator

Response: Decorator that replaces any instances of the option class with the custom OneUseOption class.


Instruction:
Create a Python 3 function for
converting a server specification to a list of matching server docs.

Response:
def _spec_to_matches(server_list, server_spec, mode):
    """
    mode is in {uri, hostname, hostname_port}

    A list of matching server docs.
    Should usually be 0 or 1 matches. Multiple matches are possible though.
    """
    assert mode in ("uri", "hostname", "hostname_port")

    def match(server_doc):
        if mode == "hostname":
            return server_spec == server_doc["hostname"]
        elif mode == "hostname_port":
            return server_spec == "{}:{}".format(
                server_doc["hostname"], server_doc["port"]
            )
        elif mode == "uri":
            return server_spec == "{}://{}:{}".format(
                server_doc["scheme"], server_doc["hostname"], server_doc["port"]
            )
        else:
            raise NotImplementedError("Unreachable error! Something is very wrong.")

    return [server_doc for server_doc in server_list if match(server_doc)]


Instruction:
Can you generate the documentation for the following Python 3 function
def server_delete(endpoint_id, server):
    client = get_client()

    mode = _detect_mode(server)

    # list (even if not necessary) in order to make errors more consistent when
    # mode='id'
    endpoint, server_list = get_endpoint_w_server_list(endpoint_id)

    if server_list == "S3":
        raise click.UsageError("You cannot delete servers from S3 endpoints.")

    # we don't *have to* raise an error in the GCP case, since the API would
    # deny it too, but doing so makes our errors a little bit more consistent
    # with deletes against S3 endpoints and shares
    if endpoint["is_globus_connect"]:
        raise click.UsageError(
            "You cannot delete servers from Globus Connect Personal endpoints"
        )

    if mode != "id":
        matches = _spec_to_matches(server_list, server, mode)
        if not matches:
            raise click.UsageError('No server was found matching "{}"'.format(server))
        elif len(matches) > 1:
            raise click.UsageError(
                dedent(
                    """\
                Multiple servers matched "{}":
                    {}
            """
                ).format(server, [x["id"] for x in matches])
            )
        else:
            server = matches[0]["id"]

    response = client.delete_endpoint_server(endpoint_id, server)

    formatted_print(response, text_format=FORMAT_TEXT_RAW, response_key="message")

Response: Executor for globus endpoint server delete


Instruction:
Can you generate a brief explanation for the following Python 3 code
def show_command(endpoint_id, rule_id):
    client = get_client()

    rule = client.get_endpoint_acl_rule(endpoint_id, rule_id)
    formatted_print(
        rule,
        text_format=FORMAT_TEXT_RECORD,
        fields=(
            ("Rule ID", "id"),
            ("Permissions", "permissions"),
            ("Shared With", _shared_with_keyfunc),
            ("Path", "path"),
        ),
    )

Response: Executor for globus endpoint permission show


Instruction:
Can you tell what is the following Python 3 function doing
def show_command(parameter):
    section = "cli"
    if "." in parameter:
        section, parameter = parameter.split(".", 1)

    value = lookup_option(parameter, section=section)

    if value is None:
        safeprint("{} not set".format(parameter))
    else:
        safeprint("{} = {}".format(parameter, value))

Response: Executor for globus config show


Instruction:
Given the following Python 3 function, write the documentation
def rename_command(source, destination):
    source_ep, source_path = source
    dest_ep, dest_path = destination

    if source_ep != dest_ep:
        raise click.UsageError(
            (
                "rename requires that the source and dest "
                "endpoints are the same, {} != {}"
            ).format(source_ep, dest_ep)
        )
    endpoint_id = source_ep

    client = get_client()
    autoactivate(client, endpoint_id, if_expires_in=60)

    res = client.operation_rename(endpoint_id, oldpath=source_path, newpath=dest_path)
    formatted_print(res, text_format=FORMAT_TEXT_RAW, response_key="message")

Response: Executor for globus rename


Instruction:
How would you explain what the following Python 3 function does
def _format_value(self, val):
        name = self.name + ":"
        if not self.multiline or "\n" not in val:
            val = u"{0} {1}".format(name.ljust(self._text_prefix_len), val)
        else:
            spacer = "\n" + " " * (self._text_prefix_len + 1)
            val = u"{0}{1}{2}".format(name, spacer, spacer.join(val.split("\n")))

        return val

Response: Formats a value to be good for textmode printing


Instruction:
Can you tell what is the following Python 3 function doing
def delete_command(endpoint_id, rule_id):
    client = get_client()

    res = client.delete_endpoint_acl_rule(endpoint_id, rule_id)
    formatted_print(res, text_format=FORMAT_TEXT_RAW, response_key="message")

Response: Executor for globus endpoint permission delete


Instruction:
Can you generate a brief explanation for the following Python 3 code
def transfer_command(
    batch,
    sync_level,
    recursive,
    destination,
    source,
    label,
    preserve_mtime,
    verify_checksum,
    encrypt,
    submission_id,
    dry_run,
    delete,
    deadline,
    skip_activation_check,
    notify,
    perf_cc,
    perf_p,
    perf_pp,
    perf_udt,
):
    """
    Executor for `globus transfer`
    """
    source_endpoint, cmd_source_path = source
    dest_endpoint, cmd_dest_path = destination

    if recursive and batch:
        raise click.UsageError(
            (
                "You cannot use --recursive in addition to --batch. "
                "Instead, use --recursive on lines of --batch input "
                "which need it"
            )
        )

    if (cmd_source_path is None or cmd_dest_path is None) and (not batch):
        raise click.UsageError(
            ("transfer requires either SOURCE_PATH and DEST_PATH or " "--batch")
        )

    # because python can't handle multiple **kwargs expansions in a single
    # call, we need to get a little bit clever
    # both the performance options (of which there are a few), and the
    # notification options (also there are a few) have elements which should be
    # omitted in some cases
    # notify comes to us clean, perf opts need more care
    # put them together into a dict before passing to TransferData
    kwargs = {}
    perf_opts = dict(
        (k, v)
        for (k, v) in dict(
            perf_cc=perf_cc, perf_p=perf_p, perf_pp=perf_pp, perf_udt=perf_udt
        ).items()
        if v is not None
    )
    kwargs.update(perf_opts)
    kwargs.update(notify)

    client = get_client()
    transfer_data = TransferData(
        client,
        source_endpoint,
        dest_endpoint,
        label=label,
        sync_level=sync_level,
        verify_checksum=verify_checksum,
        preserve_timestamp=preserve_mtime,
        encrypt_data=encrypt,
        submission_id=submission_id,
        delete_destination_extra=delete,
        deadline=deadline,
        skip_activation_check=skip_activation_check,
        **kwargs
    )

    if batch:

        @click.command()
        @click.option("--recursive", "-r", is_flag=True)
        @click.argument("source_path", type=TaskPath(base_dir=cmd_source_path))
        @click.argument("dest_path", type=TaskPath(base_dir=cmd_dest_path))
        def process_batch_line(dest_path, source_path, recursive):
            """
            Parse a line of batch input and turn it into a transfer submission
            item.
            """
            transfer_data.add_item(
                str(source_path), str(dest_path), recursive=recursive
            )

        shlex_process_stdin(
            process_batch_line,
            (
                "Enter transfers, line by line, as\n\n"
                "    [--recursive] SOURCE_PATH DEST_PATH\n"
            ),
        )
    else:
        transfer_data.add_item(cmd_source_path, cmd_dest_path, recursive=recursive)

    if dry_run:
        formatted_print(
            transfer_data,
            response_key="DATA",
            fields=(
                ("Source Path", "source_path"),
                ("Dest Path", "destination_path"),
                ("Recursive", "recursive"),
            ),
        )
        # exit safely
        return

    # autoactivate after parsing all args and putting things together
    # skip this if skip-activation-check is given
    if not skip_activation_check:
        autoactivate(client, source_endpoint, if_expires_in=60)
        autoactivate(client, dest_endpoint, if_expires_in=60)

    res = client.submit_transfer(transfer_data)
    formatted_print(
        res,
        text_format=FORMAT_TEXT_RECORD,
        fields=(("Message", "message"), ("Task ID", "task_id")),
    )

Response: Executor for globus transfer


Instruction:
Explain what the following Python 3 code does
def endpoint_delete(endpoint_id):
    client = get_client()
    res = client.delete_endpoint(endpoint_id)
    formatted_print(res, text_format=FORMAT_TEXT_RAW, response_key="message")

Response: Executor for globus endpoint delete


Instruction:
Make a summary of the following Python 3 code
def init_command(default_output_format, default_myproxy_username):
    # now handle the output format, requires a little bit more care
    # first, prompt if it isn't given, but be clear that we have a sensible
    # default if they don't set it
    # then, make sure that if it is given, it's a valid format (discard
    # otherwise)
    # finally, set it only if given and valid
    if not default_output_format:
        safeprint(
            textwrap.fill(
                'This must be one of "json" or "text". Other values will be '
                "ignored. ENTER to skip."
            )
        )
        default_output_format = (
            click.prompt(
                "Default CLI output format (cli.output_format)", default="text"
            )
            .strip()
            .lower()
        )
        if default_output_format not in ("json", "text"):
            default_output_format = None

    if not default_myproxy_username:
        safeprint(textwrap.fill("ENTER to skip."))
        default_myproxy_username = click.prompt(
            "Default myproxy username (cli.default_myproxy_username)",
            default="",
            show_default=False,
        ).strip()

    # write to disk
    safeprint(
        "\n\nWriting updated config to {0}".format(os.path.expanduser("~/.globus.cfg"))
    )
    write_option(OUTPUT_FORMAT_OPTNAME, default_output_format)
    write_option(MYPROXY_USERNAME_OPTNAME, default_myproxy_username)

Response: Executor for globus config init


Instruction:
Can you tell what is the following Python 3 function doing
def detect_and_decorate(decorator, args, kwargs):
    # special behavior when invoked with only one non-keyword argument: act as
    # a normal decorator, decorating and returning that argument with
    # click.option
    if len(args) == 1 and len(kwargs) == 0 and callable(args[0]):
        return decorator(args[0])

    # if we're not doing that, we should see no positional args
    # the alternative behavior is to fall through and discard *args, but this
    # will probably confuse someone in the future when their arguments are
    # silently discarded
    elif len(args) != 0:
        raise ValueError("this decorator cannot take positional args")

    # final case: got 0 or more kwargs, no positionals
    # do the function-which-returns-a-decorator dance to produce a
    # new decorator based on the arguments given
    else:

        def inner_decorator(f):
            return decorator(f, **kwargs)

        return inner_decorator

Response: Decorator for detecting and decorating a function based on the given arguments and kwargs.


Instruction:
Given the following Python 3 function, write the documentation
def list_command(endpoint_id):
    client = get_client()

    rules = client.endpoint_acl_list(endpoint_id)

    resolved_ids = LazyIdentityMap(
        x["principal"] for x in rules if x["principal_type"] == "identity"
    )

    def principal_str(rule):
        principal = rule["principal"]
        if rule["principal_type"] == "identity":
            username = resolved_ids.get(principal)
            return username or principal
        elif rule["principal_type"] == "group":
            return (u"https://app.globus.org/groups/{}").format(principal)
        else:
            principal = rule["principal_type"]

        return principal

    formatted_print(
        rules,
        fields=[
            ("Rule ID", "id"),
            ("Permissions", "permissions"),
            ("Shared With", principal_str),
            ("Path", "path"),
        ],
    )

Response: Executor for globus endpoint permission list


Instruction:
Given the following Python 3 function, write the documentation
def bookmark_list():
    client = get_client()

    bookmark_iterator = client.bookmark_list()

    def get_ep_name(item):
        ep_id = item["endpoint_id"]
        try:
            ep_doc = client.get_endpoint(ep_id)
            return display_name_or_cname(ep_doc)
        except TransferAPIError as err:
            if err.code == "EndpointDeleted":
                return "[DELETED ENDPOINT]"
            else:
                raise err

    formatted_print(
        bookmark_iterator,
        fields=[
            ("Name", "name"),
            ("Bookmark ID", "id"),
            ("Endpoint ID", "endpoint_id"),
            ("Endpoint Name", get_ep_name),
            ("Path", "path"),
        ],
        response_key="DATA",
        json_converter=iterable_response_to_dict,
    )

Response: Executor for globus bookmark list


Instruction:
Given the following Python 3 function, write the documentation
def rm_command(
    ignore_missing,
    star_silent,
    recursive,
    enable_globs,
    endpoint_plus_path,
    label,
    submission_id,
    dry_run,
    deadline,
    skip_activation_check,
    notify,
    meow,
    heartbeat,
    polling_interval,
    timeout,
    timeout_exit_code,
):
    """
    Executor for `globus rm`
    """
    endpoint_id, path = endpoint_plus_path

    client = get_client()

    # attempt to activate unless --skip-activation-check is given
    if not skip_activation_check:
        autoactivate(client, endpoint_id, if_expires_in=60)

    delete_data = DeleteData(
        client,
        endpoint_id,
        label=label,
        recursive=recursive,
        ignore_missing=ignore_missing,
        submission_id=submission_id,
        deadline=deadline,
        skip_activation_check=skip_activation_check,
        interpret_globs=enable_globs,
        **notify
    )

    if not star_silent and enable_globs and path.endswith("*"):
        # not intuitive, but `click.confirm(abort=True)` prints to stdout
        # unnecessarily, which we don't really want...
        # only do this check if stderr is a pty
        if (
            err_is_terminal()
            and term_is_interactive()
            and not click.confirm(
                'Are you sure you want to delete all files matching "{}"?'.format(path),
                err=True,
            )
        ):
            safeprint("Aborted.", write_to_stderr=True)
            click.get_current_context().exit(1)
    delete_data.add_item(path)

    if dry_run:
        formatted_print(delete_data, response_key="DATA", fields=[("Path", "path")])
        # exit safely
        return

    # Print task submission to stderr so that `-Fjson` is still correctly
    # respected, as it will be by `task wait`
    res = client.submit_delete(delete_data)
    task_id = res["task_id"]
    safeprint(
        'Delete task submitted under ID "{}"'.format(task_id), write_to_stderr=True
    )

    # do a `task wait` equivalent, including printing and correct exit status
    task_wait_with_io(
        meow,
        heartbeat,
        polling_interval,
        timeout,
        task_id,
        timeout_exit_code,
        client=client,
    )

Response: Executor for globus rm


Instruction:
Create a Python 3 function to
prompt the user with a link to authenticate with globus auth and authorize the CLI to act on their behalf.

Response:
def do_link_auth_flow(session_params=None, force_new_client=False):
    """
    Prompts the user with a link to authenticate with globus auth
    and authorize the CLI to act on their behalf.
    """
    session_params = session_params or {}

    # get the ConfidentialApp client object
    auth_client = internal_auth_client(
        requires_instance=True, force_new_client=force_new_client
    )

    # start the Confidential App Grant flow
    auth_client.oauth2_start_flow(
        redirect_uri=auth_client.base_url + "v2/web/auth-code",
        refresh_tokens=True,
        requested_scopes=SCOPES,
    )

    # prompt
    additional_params = {"prompt": "login"}
    additional_params.update(session_params)
    linkprompt = "Please authenticate with Globus here"
    safeprint(
        "{0}:\n{1}\n{2}\n{1}\n".format(
            linkprompt,
            "-" * len(linkprompt),
            auth_client.oauth2_get_authorize_url(additional_params=additional_params),
        )
    )

    # come back with auth code
    auth_code = click.prompt("Enter the resulting Authorization Code here").strip()

    # finish auth flow
    exchange_code_and_store_config(auth_client, auth_code)
    return True


Instruction:
Given the following Python 3 function, write the documentation
def do_local_server_auth_flow(session_params=None, force_new_client=False):
    session_params = session_params or {}

    # start local server and create matching redirect_uri
    with start_local_server(listen=("127.0.0.1", 0)) as server:
        _, port = server.socket.getsockname()
        redirect_uri = "http://localhost:{}".format(port)

        # get the ConfidentialApp client object and start a flow
        auth_client = internal_auth_client(
            requires_instance=True, force_new_client=force_new_client
        )
        auth_client.oauth2_start_flow(
            refresh_tokens=True, redirect_uri=redirect_uri, requested_scopes=SCOPES
        )
        additional_params = {"prompt": "login"}
        additional_params.update(session_params)
        url = auth_client.oauth2_get_authorize_url(additional_params=additional_params)

        # open web-browser for user to log in, get auth code
        webbrowser.open(url, new=1)
        auth_code = server.wait_for_code()

    if isinstance(auth_code, LocalServerError):
        safeprint("Authorization failed: {}".format(auth_code), write_to_stderr=True)
        click.get_current_context().exit(1)
    elif isinstance(auth_code, Exception):
        safeprint(
            "Authorization failed with unexpected error:\n{}".format(auth_code),
            write_to_stderr=True,
        )
        click.get_current_context().exit(1)

    # finish auth flow and return true
    exchange_code_and_store_config(auth_client, auth_code)
    return True

Response: Starts a local server and opens a browser to authenticate the user and gets the code redirected to the server


Instruction:
Write a Python 3 function for
exchanging code for tokens and gets user info from auth.

Response:
def exchange_code_and_store_config(auth_client, auth_code):
    """
    Finishes auth flow after code is gotten from command line or local server.
    Exchanges code for tokens and gets user info from auth.
    Stores tokens and user info in config.
    """
    # do a token exchange with the given code
    tkn = auth_client.oauth2_exchange_code_for_tokens(auth_code)
    tkn = tkn.by_resource_server

    # extract access tokens from final response
    transfer_at = tkn["transfer.api.globus.org"]["access_token"]
    transfer_at_expires = tkn["transfer.api.globus.org"]["expires_at_seconds"]
    transfer_rt = tkn["transfer.api.globus.org"]["refresh_token"]
    auth_at = tkn["auth.globus.org"]["access_token"]
    auth_at_expires = tkn["auth.globus.org"]["expires_at_seconds"]
    auth_rt = tkn["auth.globus.org"]["refresh_token"]

    # revoke any existing tokens
    for token_opt in (
        TRANSFER_RT_OPTNAME,
        TRANSFER_AT_OPTNAME,
        AUTH_RT_OPTNAME,
        AUTH_AT_OPTNAME,
    ):
        token = lookup_option(token_opt)
        if token:
            auth_client.oauth2_revoke_token(token)

    # write new tokens to config
    write_option(TRANSFER_RT_OPTNAME, transfer_rt)
    write_option(TRANSFER_AT_OPTNAME, transfer_at)
    write_option(TRANSFER_AT_EXPIRES_OPTNAME, transfer_at_expires)
    write_option(AUTH_RT_OPTNAME, auth_rt)
    write_option(AUTH_AT_OPTNAME, auth_at)
    write_option(AUTH_AT_EXPIRES_OPTNAME, auth_at_expires)


Instruction:
Here you have a function in Python 3, explain what it does
def endpoint_search(filter_fulltext, filter_owner_id, filter_scope):
    if filter_scope == "all" and not filter_fulltext:
        raise click.UsageError(
            "When searching all endpoints (--filter-scope=all, the default), "
            "a full-text search filter is required. Other scopes (e.g. "
            "--filter-scope=recently-used) may be used without specifying "
            "an additional filter."
        )

    client = get_client()

    owner_id = filter_owner_id
    if owner_id:
        owner_id = maybe_lookup_identity_id(owner_id)

    search_iterator = client.endpoint_search(
        filter_fulltext=filter_fulltext,
        filter_scope=filter_scope,
        filter_owner_id=owner_id,
    )

    formatted_print(
        search_iterator,
        fields=ENDPOINT_LIST_FIELDS,
        json_converter=iterable_response_to_dict,
    )

Response: Executor for globus endpoint search


Instruction:
Write a Python 3 function for
wrapping around click. echo that does not raise IOError.

Response:
def safeprint(message, write_to_stderr=False, newline=True):
    """
    Wrapper around click.echo used to encapsulate its functionality.
    Also protects against EPIPE during click.echo calls, as this can happen
    normally in piped commands when the consumer closes before the producer.
    """
    try:
        click.echo(message, nl=newline, err=write_to_stderr)
    except IOError as err:
        if err.errno is errno.EPIPE:
            pass
        else:
            raise


Instruction:
Given the following Python 3 function, write the documentation
def _key_to_keyfunc(k):
    # if the key is a string, then the "keyfunc" is just a basic lookup
    # operation -- return that
    if isinstance(k, six.string_types):

        def lookup(x):
            return x[k]

        return lookup
    # otherwise, the key must be a function which is executed on the item
    # to produce a value -- return it verbatim
    return k

Response:
Converts a key to a function that returns a value for the item
   .


Instruction:
Given the following Python 3 function, write the documentation
def endpoint_id_arg(*args, **kwargs):

    def decorate(f, **kwargs):
        """
        Work of actually decorating a function -- wrapped in here because we
        want to dispatch depending on how this is invoked
        """
        metavar = kwargs.get("metavar", "ENDPOINT_ID")
        f = click.argument("endpoint_id", metavar=metavar, type=click.UUID)(f)
        return f

    return detect_and_decorate(decorate, args, kwargs)

Response: Decorator for handling the endpoint_id argument.


Instruction:
Write a Python 3 function that can
validate the parameters for an endpoint create and update.

Response:
def validate_endpoint_create_and_update_params(endpoint_type, managed, params):
    """
    Given an endpoint type of "shared" "server" or "personal" and option values
    Confirms the option values are valid for the given endpoint
    """
    # options only allowed for GCS endpoints
    if endpoint_type != "server":
        # catch params with two option flags
        if params["public"] is False:
            raise click.UsageError(
                "Option --private only allowed " "for Globus Connect Server endpoints"
            )
        # catch any params only usable with GCS
        for option in [
            "public",
            "myproxy_dn",
            "myproxy_server",
            "oauth_server",
            "location",
            "network_use",
            "max_concurrency",
            "preferred_concurrency",
            "max_parallelism",
            "preferred_parallelism",
        ]:
            if params[option] is not None:
                raise click.UsageError(
                    (
                        "Option --{} can only be used with Globus Connect Server "
                        "endpoints".format(option.replace("_", "-"))
                    )
                )

    # if the endpoint was not previously managed, and is not being passed
    # a subscription id, it cannot use managed endpoint only fields
    if (not managed) and not (params["subscription_id"] or params["managed"]):
        for option in [
            "network_use",
            "max_concurrency",
            "preferred_concurrency",
            "max_parallelism",
            "preferred_parallelism",
        ]:
            if params[option] is not None:
                raise click.UsageError(
                    (
                        "Option --{} can only be used with managed "
                        "endpoints".format(option.replace("_", "-"))
                    )
                )

    # because the Transfer service doesn't do network use level updates in a
    # patchy way, *both* endpoint `POST`s *and* `PUT`s must either use
    # - `network_use='custom'` with *every* other parameter specified (which
    #   is validated by the service), or
    # - a preset/absent `network_use` with *no* other parameter specified
    #   (which is *not* validated by the service; in this case, Transfer will
    #   accept but ignore the others parameters if given, leading to user
    #   confusion if we don't do this validation check)
    custom_network_use_params = (
        "max_concurrency",
        "preferred_concurrency",
        "max_parallelism",
        "preferred_parallelism",
    )
    if params["network_use"] != "custom":
        for option in custom_network_use_params:
            if params[option] is not None:
                raise click.UsageError(
                    "The {} options require you use --network-use=custom.".format(
                        "/".join(
                            "--" + option.replace("_", "-")
                            for option in custom_network_use_params
                        )
                    )
                )

    # make sure --(no-)managed and --subscription-id are mutually exclusive
    # if --managed given pass DEFAULT as the subscription_id
    # if --no-managed given, pass None
    managed_flag = params.get("managed")
    if managed_flag is not None:
        params.pop("managed")
        if managed_flag:
            params["subscription_id"] = params.get("subscription_id") or "DEFAULT"
        else:
            if params.get("subscription_id"):
                raise click.UsageError(
                    "Cannot specify --subscription-id and "
                    "use the --no-managed option."
                )
            params["subscription_id"] = EXPLICIT_NULL

    # make sure --no-default-directory are mutually exclusive
    # if --no-managed given, pass an EXPLICIT_NULL as the default directory
    if params.get("no_default_directory"):

        if params.get("default_directory"):
            raise click.UsageError(
                "--no-default-directory and --default-directory are mutually "
                "exclusive."
            )
        else:
            params["default_directory"] = EXPLICIT_NULL
            params.pop("no_default_directory")


Instruction:
How would you explain what the following Python 3 function does
def task_id_arg(*args, **kwargs):

    def inner_decorator(f, required=True):
        f = click.argument("TASK_ID", required=required)(f)
        return f

    return detect_and_decorate(inner_decorator, args, kwargs)

Response: Decorator to specify the TASK_ID argument for a Transfer Task.


Instruction:
Make a summary of the following Python 3 code
def task_submission_options(f):

    def notify_opt_callback(ctx, param, value):
        """
        Parse --notify
        - "" is the same as "off"
        - parse by lowercase, comma-split, strip spaces
        - "off,x" is invalid for any x
        - "on,x" is valid for any valid x (other than "off")
        - "failed", "succeeded", "inactive" are normal vals

        In code, produces True, False, or a set
        """
        # if no value was set, don't set any explicit options
        # the API default is "everything on"
        if value is None:
            return {}

        value = value.lower()
        value = [x.strip() for x in value.split(",")]
        # [""] is what you'll get if value is "" to start with
        # special-case it into "off", which helps avoid surprising scripts
        # which take a notification settings as inputs and build --notify
        if value == [""]:
            value = ["off"]

        off = "off" in value
        on = "on" in value
        # set-ize it -- duplicates are fine
        vals = set([x for x in value if x not in ("off", "on")])

        if (vals or on) and off:
            raise click.UsageError('--notify cannot accept "off" and another value')

        allowed_vals = set(("on", "succeeded", "failed", "inactive"))
        if not vals <= allowed_vals:
            raise click.UsageError(
                "--notify received at least one invalid value among {}".format(
                    list(vals)
                )
            )

        # return the notification options to send!
        # on means don't set anything (default)
        if on:
            return {}
        # off means turn off everything
        if off:
            return {
                "notify_on_succeeded": False,
                "notify_on_failed": False,
                "notify_on_inactive": False,
            }
        # otherwise, return the exact set of values seen
        else:
            return {
                "notify_on_succeeded": "succeeded" in vals,
                "notify_on_failed": "failed" in vals,
                "notify_on_inactive": "inactive" in vals,
            }

    f = click.option(
        "--dry-run",
        is_flag=True,
        help=("Don't actually submit the task, print submission " "data instead"),
    )(f)
    f = click.option(
        "--notify",
        callback=notify_opt_callback,
        help=(
            "Comma separated list of task events which notify by email. "
            "'on' and 'off' may be used to enable or disable notifications "
            "for all event types. Otherwise, use 'succeeded', 'failed', or "
            "'inactive'"
        ),
    )(f)
    f = click.option(
        "--submission-id",
        help=(
            "Task submission ID, as generated by `globus task "
            "generate-submission-id`. Used for safe resubmission in the "
            "presence of network failures."
        ),
    )(f)
    f = click.option("--label", default=None, help="Set a label for this task.")(f)
    f = click.option(
        "--deadline",
        default=None,
        type=ISOTimeType(),
        help="Set a deadline for this to be canceled if not completed by.",
    )(f)
    f = click.option(
        "--skip-activation-check",
        is_flag=True,
        help=("Submit the task even if the endpoint(s) " "aren't currently activated."),
    )(f)

    return f

Response: This function returns a list of options shared by both transfer and delete tasks.


Instruction:
Here you have a function in Python 3, explain what it does
def delete_and_rm_options(*args, **kwargs):

    def inner_decorator(f, supports_batch=True, default_enable_globs=False):
        f = click.option(
            "--recursive", "-r", is_flag=True, help="Recursively delete dirs"
        )(f)
        f = click.option(
            "--ignore-missing",
            "-f",
            is_flag=True,
            help="Don't throw errors if the file or dir is absent",
        )(f)
        f = click.option(
            "--star-silent",
            "--unsafe",
            "star_silent",
            is_flag=True,
            help=(
                'Don\'t prompt when the trailing character is a "*".'
                + (" Implicit in --batch" if supports_batch else "")
            ),
        )(f)
        f = click.option(
            "--enable-globs/--no-enable-globs",
            is_flag=True,
            default=default_enable_globs,
            show_default=True,
            help=(
                "Enable expansion of *, ?, and [ ] characters in the last "
                "component of file paths, unless they are escaped with "
                "a preceeding backslash, \\"
            ),
        )(f)
        if supports_batch:
            f = click.option(
                "--batch",
                is_flag=True,
                help=(
                    "Accept a batch of paths on stdin (i.e. run in "
                    "batchmode). Uses ENDPOINT_ID as passed on the "
                    "commandline. Any commandline PATH given will be used "
                    "as a prefix to all paths given"
                ),
            )(f)
        return f

    return detect_and_decorate(inner_decorator, args, kwargs)

Response: Decorator to add globus delete and globus rm options to a single globus archive.