Instruction:
Write a Python 3 function that can
write as a BEL namespace file.

Response:
def write_bel_namespace(self, file: TextIO, use_names: bool = False) -> None:
        """Write as a BEL namespace file."""
        if not self.is_populated():
            self.populate()

        if use_names and not self.has_names:
            raise ValueError

        values = (
            self._get_namespace_name_to_encoding(desc='writing names')
            if use_names else
            self._get_namespace_identifier_to_encoding(desc='writing identifiers')
        )

        write_namespace(
            namespace_name=self._get_namespace_name(),
            namespace_keyword=self._get_namespace_keyword(),
            namespace_query_url=self.identifiers_url,
            values=values,
            file=file,
        )


Instruction:
Can you tell what is the following Python 3 function doing
def write_bel_annotation(self, file: TextIO) -> None:
        if not self.is_populated():
            self.populate()

        values = self._get_namespace_name_to_encoding(desc='writing names')

        write_annotation(
            keyword=self._get_namespace_keyword(),
            citation_name=self._get_namespace_name(),
            description='',
            values=values,
            file=file,
        )

Response: Write as a BEL annotation file.


Instruction:
Can you implement a function in Python 3 that
writes a BEL namespace mapping file.

Response:
def write_bel_namespace_mappings(self, file: TextIO, **kwargs) -> None:
        """Write a BEL namespace mapping file."""
        json.dump(self._get_namespace_identifier_to_name(**kwargs), file, indent=2, sort_keys=True)


Instruction:
Implement a function in Python 3 to
write a BEL namespace for identifiers names name hash and mappings to the given directory.

Response:
def write_directory(self, directory: str) -> bool:
        """Write a BEL namespace for identifiers, names, name hash, and mappings to the given directory."""
        current_md5_hash = self.get_namespace_hash()
        md5_hash_path = os.path.join(directory, f'{self.module_name}.belns.md5')

        if not os.path.exists(md5_hash_path):
            old_md5_hash = None
        else:
            with open(md5_hash_path) as file:
                old_md5_hash = file.read().strip()

        if old_md5_hash == current_md5_hash:
            return False

        with open(os.path.join(directory, f'{self.module_name}.belns'), 'w') as file:
            self.write_bel_namespace(file, use_names=False)

        with open(md5_hash_path, 'w') as file:
            print(current_md5_hash, file=file)

        if self.has_names:
            with open(os.path.join(directory, f'{self.module_name}-names.belns'), 'w') as file:
                self.write_bel_namespace(file, use_names=True)

            with open(os.path.join(directory, f'{self.module_name}.belns.mapping'), 'w') as file:
                self.write_bel_namespace_mappings(file, desc='writing mapping')

        return True


Instruction:
Write a Python 3 script for
getting the namespace hash.

Response:
def get_namespace_hash(self, hash_fn=hashlib.md5) -> str:
        """Get the namespace hash.

        Defaults to MD5.
        """
        m = hash_fn()

        if self.has_names:
            items = self._get_namespace_name_to_encoding(desc='getting hash').items()
        else:
            items = self._get_namespace_identifier_to_encoding(desc='getting hash').items()

        for name, encoding in items:
            m.update(f'{name}:{encoding}'.encode('utf8'))
        return m.hexdigest()


Instruction:
Make a summary of the following Python 3 code
def get_cli(cls) -> click.Group:
        main = super().get_cli()

        if cls.is_namespace:
            @main.group()
            def belns():
                """Manage BEL namespace."""

            cls._cli_add_to_bel_namespace(belns)
            cls._cli_add_clear_bel_namespace(belns)
            cls._cli_add_write_bel_namespace(belns)

        if cls.is_annotation:
            @main.group()
            def belanno():
                """Manage BEL annotation."""

            cls._cli_add_write_bel_annotation(belanno)

        return main

Response: Get a click. Group that adds BEL namespace commands.


Instruction:
How would you explain what the following Python 3 function does
def get_long_description():
    with codecs.open(os.path.join(HERE, 'README.rst'), encoding='utf-8') as f:
        long_description = f.read()
    return long_description

Response: Get the long_description from the README. rst file. Assume UTF - 8 encoding.


Instruction:
How would you explain what the following Python 3 function does
def dropbox_post_factory(request):
    try:
        max_age = int(request.registry.settings.get('post_token_max_age_seconds'))
    except Exception:
        max_age = 300

    try:
        drop_id = parse_post_token(
            token=request.matchdict['token'],
            secret=request.registry.settings['post_secret'],
            max_age=max_age)
    except SignatureExpired:
        raise HTTPGone('dropbox expired')
    except Exception:  # don't be too specific on the reason for the error
        raise HTTPNotFound('no such dropbox')
    dropbox = request.registry.settings['dropbox_container'].get_dropbox(drop_id)
    if dropbox.status_int >= 20:
        raise HTTPGone('dropbox already in processing, no longer accepts data')
    return dropbox

Response:
receives a UUID via the request and returns either a fresh or existing dropbox
    for it


Instruction:
How would you code a function in Python 3 to
expect the id of an existing dropbox and returns its instance

Response:
def dropbox_factory(request):
    """ expects the id of an existing dropbox and returns its instance"""
    try:
        return request.registry.settings['dropbox_container'].get_dropbox(request.matchdict['drop_id'])
    except KeyError:
        raise HTTPNotFound('no such dropbox')


Instruction:
Can you generate the documentation for the following Python 3 function
def is_equal(a, b):
    if len(a) != len(b):
        return False

    result = 0
    for x, y in zip(a, b):
        result |= ord(x) ^ ord(y)
    return result == 0

Response: a constant time comparison implementation taken from Codahale s RFC 2965


Instruction:
How would you explain what the following Python 3 function does
def get_cli(cls) -> click.Group:
        group_help = 'Default connection at {}\n\nusing Bio2BEL v{}'.format(cls._get_connection(), get_version())

        @click.group(help=group_help)
        @click.option('-c', '--connection', default=cls._get_connection(),
                      help='Defaults to {}'.format(cls._get_connection()))
        @click.pass_context
        def main(ctx, connection):
            """Bio2BEL CLI."""
            logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
            logging.getLogger('bio2bel.utils').setLevel(logging.WARNING)
            ctx.obj = cls(connection=connection)

        return main

Response: Build a click CLI main function.


Instruction:
Can you write a function in Python 3 where it
preserves the file ending but replace the name with a random token

Response:
def sanitize_filename(filename):
    """preserve the file ending, but replace the name with a random token """
    # TODO: fix broken splitext (it reveals everything of the filename after the first `.` - doh!)
    token = generate_drop_id()
    name, extension = splitext(filename)
    if extension:
        return '%s%s' % (token, extension)
    else:
        return token


Instruction:
How would you implement a function in Python 3 that
calls the external cleanser scripts to purge the meta data and then send the contents of the dropbox via email.

Response:
def process(self):
        """ Calls the external cleanser scripts to (optionally) purge the meta data and then
            send the contents of the dropbox via email.
        """

        if self.num_attachments > 0:
            self.status = u'100 processor running'
            fs_dirty_archive = self._create_backup()
            # calling _process_attachments has the side-effect of updating `send_attachments`
            self._process_attachments()
            if self.status_int < 500 and not self.send_attachments:
                    self._create_archive()

        if self.status_int >= 500 and self.status_int < 600:
            # cleansing failed
            # if configured, we need to move the uncleansed archive to
            # the appropriate folder and notify the editors
            if 'dropbox_dirty_archive_url_format' in self.settings:
                # create_archive
                shutil.move(
                    fs_dirty_archive,
                    '%s/%s.zip.pgp' % (self.container.fs_archive_dirty, self.drop_id))
                # update status
                # it's now considered 'successful-ish' again
                self.status = '490 cleanser failure but notify success'

        if self.status_int == 800:
            # at least one attachment was not supported
            # if configured, we need to move the uncleansed archive to
            # the appropriate folder and notify the editors
            if 'dropbox_dirty_archive_url_format' in self.settings:
                # create_archive
                shutil.move(
                    fs_dirty_archive,
                    '%s/%s.zip.pgp' % (self.container.fs_archive_dirty, self.drop_id))

        if self.status_int < 500 or self.status_int == 800:
            try:
                if self._notify_editors() > 0:
                    if self.status_int < 500:
                        self.status = '900 success'
                else:
                    self.status = '605 smtp failure'
            except Exception:
                import traceback
                tb = traceback.format_exc()
                self.status = '610 smtp error (%s)' % tb

        self.cleanup()
        return self.status


Instruction:
How would you explain what the following Python 3 function does
def cleanup(self):
        try:
            remove(join(self.fs_path, u'message'))
            remove(join(self.fs_path, 'dirty.zip.pgp'))
        except OSError:
            pass
        shutil.rmtree(join(self.fs_path, u'clean'), ignore_errors=True)
        shutil.rmtree(join(self.fs_path, u'attach'), ignore_errors=True)

Response: Removes all data except the status file and clean the directory.


Instruction:
Can you write a function in Python 3 where it
creates a zip file from the drop and encrypts it to the editors.

Response:
def _create_encrypted_zip(self, source='dirty', fs_target_dir=None):
        """ creates a zip file from the drop and encrypts it to the editors.
        the encrypted archive is created inside fs_target_dir"""
        backup_recipients = [r for r in self.editors if checkRecipient(self.gpg_context, r)]

        # this will be handled by watchdog, no need to send for each drop
        if not backup_recipients:
            self.status = u'500 no valid keys at all'
            return self.status

        # calculate paths
        fs_backup = join(self.fs_path, '%s.zip' % source)
        if fs_target_dir is None:
            fs_backup_pgp = join(self.fs_path, '%s.zip.pgp' % source)
        else:
            fs_backup_pgp = join(fs_target_dir, '%s.zip.pgp' % self.drop_id)
        fs_source = dict(
            dirty=self.fs_dirty_attachments,
            clean=self.fs_cleansed_attachments
        )

        # create archive
        with ZipFile(fs_backup, 'w', ZIP_STORED) as backup:
            if exists(join(self.fs_path, 'message')):
                backup.write(join(self.fs_path, 'message'), arcname='message')
            for fs_attachment in fs_source[source]:
                backup.write(fs_attachment, arcname=split(fs_attachment)[-1])

        # encrypt archive
        with open(fs_backup, "rb") as backup:
            self.gpg_context.encrypt_file(
                backup,
                backup_recipients,
                always_trust=True,
                output=fs_backup_pgp
            )

        # cleanup
        remove(fs_backup)
        return fs_backup_pgp


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _create_archive(self):
        self.status = u'270 creating final encrypted backup of cleansed attachments'
        return self._create_encrypted_zip(source='clean', fs_target_dir=self.container.fs_archive_cleansed)

Response: Creates an encrypted archive of the dropbox inside of the drop directory.


Instruction:
How would you code a function in Python 3 to
return the number of bytes that the cleansed attachments take up on disk

Response:
def size_attachments(self):
        """returns the number of bytes that the cleansed attachments take up on disk"""
        total_size = 0
        for attachment in self.fs_cleansed_attachments:
                total_size += stat(attachment).st_size
        return total_size


Instruction:
Can you generate a brief explanation for the following Python 3 code
def replies(self):
        fs_reply_path = join(self.fs_replies_path, 'message_001.txt')
        if exists(fs_reply_path):
            return [load(open(fs_reply_path, 'r'))]
        else:
            return []

Response: returns a list of strings


Instruction:
Explain what the following Python 3 code does
def message(self):
        try:
            with open(join(self.fs_path, u'message')) as message_file:
                return u''.join([line.decode('utf-8') for line in message_file.readlines()])
        except IOError:
            return u''

Response: returns the user submitted text


Instruction:
Can you write a function in Python 3 where it
returns a list of absolute paths to the attachments that have been changed

Response:
def fs_dirty_attachments(self):
        """ returns a list of absolute paths to the attachements"""
        if exists(self.fs_attachment_container):
            return [join(self.fs_attachment_container, attachment)
                    for attachment in listdir(self.fs_attachment_container)]
        else:
            return []


Instruction:
How would you code a function in Python 3 to
return a list of absolute paths to the cleansed attachments

Response:
def fs_cleansed_attachments(self):
        """ returns a list of absolute paths to the cleansed attachements"""
        if exists(self.fs_cleansed_attachment_container):
            return [join(self.fs_cleansed_attachment_container, attachment)
                    for attachment in listdir(self.fs_cleansed_attachment_container)]
        else:
            return []


Instruction:
Can you implement a function in Python 3 that
destroys all cleanser slaves and rollback snapshots as well as the initial master snapshot

Response:
def reset_cleansers(confirm=True):
    """destroys all cleanser slaves and their rollback snapshots, as well as the initial master
    snapshot - this allows re-running the jailhost deployment to recreate fresh cleansers."""

    if value_asbool(confirm) and not yesno("""\nObacht!
            This will destroy any existing and or currently running cleanser jails.
            Are you sure that you want to continue?"""):
        exit("Glad I asked...")

    get_vars()

    cleanser_count = AV['ploy_cleanser_count']
    # make sure no workers interfere:
    fab.run('ezjail-admin stop worker')
    # stop and nuke the cleanser slaves
    for cleanser_index in range(cleanser_count):
        cindex = '{:02d}'.format(cleanser_index + 1)
        fab.run('ezjail-admin stop cleanser_{cindex}'.format(cindex=cindex))
        with fab.warn_only():
            fab.run('zfs destroy tank/jails/cleanser_{cindex}@jdispatch_rollback'.format(cindex=cindex))
            fab.run('ezjail-admin delete -fw cleanser_{cindex}'.format(cindex=cindex))
            fab.run('umount -f /usr/jails/cleanser_{cindex}'.format(cindex=cindex))
            fab.run('rm -rf /usr/jails/cleanser_{cindex}'.format(cindex=cindex))

    with fab.warn_only():
        # remove master snapshot
        fab.run('zfs destroy -R tank/jails/cleanser@clonesource')

        # restart worker and cleanser to prepare for subsequent ansible configuration runs
        fab.run('ezjail-admin start worker')
        fab.run('ezjail-admin stop cleanser')
        fab.run('ezjail-admin start cleanser')


Instruction:
Given the following Python 3 function, write the documentation
def reset_jails(confirm=True, keep_cleanser_master=True):
    if value_asbool(confirm) and not yesno("""\nObacht!
            This will destroy all existing and or currently running jails on the host.
            Are you sure that you want to continue?"""):
        exit("Glad I asked...")

    reset_cleansers(confirm=False)

    jails = ['appserver', 'webserver', 'worker']
    if not value_asbool(keep_cleanser_master):
        jails.append('cleanser')

    with fab.warn_only():
        for jail in jails:
            fab.run('ezjail-admin delete -fw {jail}'.format(jail=jail))
        # remove authorized keys for no longer existing key (they are regenerated for each new worker)
        fab.run('rm /usr/jails/cleanser/usr/home/cleanser/.ssh/authorized_keys')

Response: Stops deletes and re - creates all jails.


Instruction:
Given the following Python 3 function, write the documentation
def dict_dumper(provider):
    '''
    Dump a provider to a format that can be passed to a
    :class:`skosprovider.providers.DictionaryProvider`.

    :param skosprovider.providers.VocabularyProvider provider: The provider
        that wil be turned into a `dict`.
    :rtype: A list of dicts.

    .. versionadded:: 0.2.0
    '''
    ret = []
    for stuff in provider.get_all():
        c = provider.get_by_id(stuff['id'])
        labels = [l.__dict__ for l in c.labels]
        notes = [n.__dict__ for n in c.notes]
        sources = [s.__dict__ for s in c.sources]
        if isinstance(c, Concept):
            ret.append({
                'id': c.id,
                'uri': c.uri,
                'type': c.type,
                'labels': labels,
                'notes': notes,
                'sources': sources,
                'narrower': c.narrower,
                'broader': c.broader,
                'related': c.related,
                'member_of': c.member_of,
                'subordinate_arrays': c.subordinate_arrays,
                'matches': c.matches
            })
        elif isinstance(c, Collection):
            ret.append({
                'id': c.id,
                'uri': c.uri,
                'type': c.type,
                'labels': labels,
                'notes': notes,
                'sources': sources,
                'members': c.members,
                'member_of': c.member_of,
                'superordinates': c.superordinates
            })
    return ret

Response: Dumps a provider to a list of dicts.


Instruction:
Explain what the following Python 3 code does
def add_cli_flask(main: click.Group) -> click.Group:  # noqa: D202

    @main.command()
    @click.option('-v', '--debug', is_flag=True)
    @click.option('-p', '--port')
    @click.option('-h', '--host')
    @click.option('-k', '--secret-key', default=os.urandom(8))
    @click.pass_obj
    def web(manager, debug, port, host, secret_key):
        """Run the web app."""
        if not manager.is_populated():
            click.echo('{} has not yet been populated'.format(manager.module_name))
            sys.exit(0)

        app = manager.get_flask_admin_app(url='/', secret_key=secret_key)
        app.run(debug=debug, host=host, port=port)

    return main

Response: Add a web comand main.


Instruction:
Implement a Python 3 function for
adding a Flask Admin interface to an application.

Response:
def _add_admin(self, app, **kwargs):
        """Add a Flask Admin interface to an application.

        :param flask.Flask app: A Flask application
        :param kwargs: Keyword arguments are passed through to :class:`flask_admin.Admin`
        :rtype: flask_admin.Admin
        """
        from flask_admin import Admin
        from flask_admin.contrib.sqla import ModelView

        admin = Admin(app, **kwargs)

        for flask_admin_model in self.flask_admin_models:
            if isinstance(flask_admin_model, tuple):  # assume its a 2 tuple
                if len(flask_admin_model) != 2:
                    raise TypeError

                model, view = flask_admin_model
                admin.add_view(view(model, self.session))

            else:
                admin.add_view(ModelView(flask_admin_model, self.session))

        return admin


Instruction:
Here you have a function in Python 3, explain what it does
def get_flask_admin_app(self, url: Optional[str] = None, secret_key: Optional[str] = None):
        from flask import Flask

        app = Flask(__name__)

        if secret_key:
            app.secret_key = secret_key

        self._add_admin(app, url=(url or '/'))
        return app

Response: Create a Flask application.


Instruction:
How would you implement a function in Python 3 that
adds a click. Group to use as a command line interface.

Response:
def get_cli(cls) -> click.Group:
        """Add  a :mod:`click` main function to use as a command line interface."""
        main = super().get_cli()

        cls._cli_add_flask(main)

        return main


Instruction:
Implement a function in Python 3 to
handle a system status event.

Response:
def _handle_system_status_event(self, event: SystemStatusEvent) -> None:
        """
        DISARMED -> ARMED_AWAY -> EXIT_DELAY_START -> EXIT_DELAY_END
         (trip): -> ALARM -> OUTPUT_ON -> ALARM_RESTORE
            (disarm): -> DISARMED -> OUTPUT_OFF
         (disarm): -> DISARMED
         (disarm before EXIT_DELAY_END): -> DISARMED -> EXIT_DELAY_END

        TODO(NW): Check ALARM_RESTORE state transition to move back into ARMED_AWAY state
        """
        if event.type == SystemStatusEvent.EventType.UNSEALED:
            return self._update_zone(event.zone, True)
        elif event.type == SystemStatusEvent.EventType.SEALED:
            return self._update_zone(event.zone, False)
        elif event.type == SystemStatusEvent.EventType.ALARM:
            return self._update_arming_state(ArmingState.TRIGGERED)
        elif event.type == SystemStatusEvent.EventType.ALARM_RESTORE:
            if self.arming_state != ArmingState.DISARMED:
                return self._update_arming_state(ArmingState.ARMED)
        elif event.type == SystemStatusEvent.EventType.ENTRY_DELAY_START:
            return self._update_arming_state(ArmingState.ENTRY_DELAY)
        elif event.type == SystemStatusEvent.EventType.ENTRY_DELAY_END:
            pass
        elif event.type == SystemStatusEvent.EventType.EXIT_DELAY_START:
            return self._update_arming_state(ArmingState.EXIT_DELAY)
        elif event.type == SystemStatusEvent.EventType.EXIT_DELAY_END:
            # Exit delay finished - if we were in the process of arming update
            # state to armed
            if self.arming_state == ArmingState.EXIT_DELAY:
                return self._update_arming_state(ArmingState.ARMED)
        elif event.type in Alarm.ARM_EVENTS:
            return self._update_arming_state(ArmingState.ARMING)
        elif event.type == SystemStatusEvent.EventType.DISARMED:
            return self._update_arming_state(ArmingState.DISARMED)
        elif event.type == SystemStatusEvent.EventType.ARMING_DELAYED:
            pass


Instruction:
Given the following Python 3 function, write the documentation
def dropbox_form(request):
    from briefkasten import generate_post_token
    token = generate_post_token(secret=request.registry.settings['post_secret'])
    return dict(
        action=request.route_url('dropbox_form_submit', token=token),
        fileupload_url=request.route_url('dropbox_fileupload', token=token),
        **defaults(request))

Response: Generates a dropbox uid and renders the submission form with a signed version of that id


Instruction:
Make a summary of the following Python 3 code
def dropbox_fileupload(dropbox, request):
    attachment = request.POST['attachment']
    attached = dropbox.add_attachment(attachment)
    return dict(
        files=[dict(
            name=attached,
            type=attachment.type,
        )]
    )

Response: accepts a single file upload and adds it to the dropbox as attachment


Instruction:
Implement a Python 3 function for
handling the form submission redirects to the dropbox s status page

Response:
def dropbox_submission(dropbox, request):
    """ handles the form submission, redirects to the dropbox's status page."""
    try:
        data = dropbox_schema.deserialize(request.POST)
    except Exception:
        return HTTPFound(location=request.route_url('dropbox_form'))

    # set the message
    dropbox.message = data.get('message')

    # recognize submission from watchdog
    if 'testing_secret' in dropbox.settings:
        dropbox.from_watchdog = is_equal(
            unicode(dropbox.settings['test_submission_secret']),
            data.pop('testing_secret', u''))

    # a non-js client might have uploaded an attachment via the form's fileupload field:
    if data.get('upload') is not None:
        dropbox.add_attachment(data['upload'])

    # now we can call the process method
    dropbox.submit()
    drop_url = request.route_url('dropbox_view', drop_id=dropbox.drop_id)
    print("Created dropbox %s" % drop_url)
    return HTTPFound(location=drop_url)


Instruction:
Can you create a Python 3 function that
builds a function that downloads and parses a GO OBO file and returns a MultiDiGraph.

Response:
def make_obo_getter(data_url: str,
                    data_path: str,
                    *,
                    preparsed_path: Optional[str] = None,
                    ) -> Callable[[Optional[str], bool, bool], MultiDiGraph]:
    """Build a function that handles downloading OBO data and parsing it into a NetworkX object.

    :param data_url: The URL of the data
    :param data_path: The path where the data should get stored
    :param preparsed_path: The optional path to cache a pre-parsed json version
    """
    download_function = make_downloader(data_url, data_path)

    def get_obo(url: Optional[str] = None, cache: bool = True, force_download: bool = False) -> MultiDiGraph:
        """Download and parse a GO obo file with :mod:`obonet` into a MultiDiGraph.

        :param url: The URL (or file path) to download.
        :param cache: If true, the data is downloaded to the file system, else it is loaded from the internet
        :param force_download: If true, overwrites a previously cached file
        """
        if preparsed_path is not None and os.path.exists(preparsed_path):
            return read_gpickle(preparsed_path)

        if url is None and cache:
            url = download_function(force_download=force_download)

        result = obonet.read_obo(url)

        if preparsed_path is not None:
            write_gpickle(result, preparsed_path)

        return result

    return get_obo


Instruction:
Can you generate the documentation for the following Python 3 function
def belns(keyword: str, file: TextIO, encoding: Optional[str], use_names: bool):
    directory = get_data_dir(keyword)
    obo_url = f'http://purl.obolibrary.org/obo/{keyword}.obo'
    obo_path = os.path.join(directory, f'{keyword}.obo')
    obo_cache_path = os.path.join(directory, f'{keyword}.obo.pickle')

    obo_getter = make_obo_getter(obo_url, obo_path, preparsed_path=obo_cache_path)
    graph = obo_getter()
    convert_obo_graph_to_belns(
        graph,
        file=file,
        encoding=encoding,
        use_names=use_names,
    )

Response: Write as a BEL namespace.


Instruction:
Make a summary of the following Python 3 code
def belanno(keyword: str, file: TextIO):
    directory = get_data_dir(keyword)
    obo_url = f'http://purl.obolibrary.org/obo/{keyword}.obo'
    obo_path = os.path.join(directory, f'{keyword}.obo')
    obo_cache_path = os.path.join(directory, f'{keyword}.obo.pickle')

    obo_getter = make_obo_getter(obo_url, obo_path, preparsed_path=obo_cache_path)
    graph = obo_getter()
    convert_obo_graph_to_belanno(
        graph,
        file=file,
    )

Response: Write as a BEL annotation.


Instruction:
How would you code a function in Python 3 to
help store an action.

Response:
def _store_helper(model: Action, session: Optional[Session] = None) -> None:
    """Help store an action."""
    if session is None:
        session = _make_session()

    session.add(model)
    session.commit()
    session.close()


Instruction:
Can you implement a function in Python 3 that
creates the tables for Bio2BEL.

Response:
def create_all(engine, checkfirst=True):
    """Create the tables for Bio2BEL."""
    Base.metadata.create_all(bind=engine, checkfirst=checkfirst)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def store_populate(cls, resource: str, session: Optional[Session] = None) -> 'Action':
        action = cls.make_populate(resource)
        _store_helper(action, session=session)
        return action

Response: Store a populate event.


Instruction:
Can you generate the documentation for the following Python 3 function
def store_populate_failed(cls, resource: str, session: Optional[Session] = None) -> 'Action':
        action = cls.make_populate_failed(resource)
        _store_helper(action, session=session)
        return action

Response: Store a populate failed event.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def store_drop(cls, resource: str, session: Optional[Session] = None) -> 'Action':
        action = cls.make_drop(resource)
        _store_helper(action, session=session)
        return action

Response: Store a drop event.


Instruction:
Can you write a function in Python 3 where it
ensures the appropriate Bio2BEL data directory exists for the given module.

Response:
def get_data_dir(module_name: str) -> str:
    """Ensure the appropriate Bio2BEL data directory exists for the given module, then returns the file path.

    :param module_name: The name of the module. Ex: 'chembl'
    :return: The module's data directory
    """
    module_name = module_name.lower()
    data_dir = os.path.join(BIO2BEL_DIR, module_name)
    os.makedirs(data_dir, exist_ok=True)
    return data_dir


Instruction:
How would you code a function in Python 3 to
build a module configuration class.

Response:
def get_module_config_cls(module_name: str) -> Type[_AbstractModuleConfig]:  # noqa: D202
    """Build a module configuration class."""

    class ModuleConfig(_AbstractModuleConfig):
        NAME = f'bio2bel:{module_name}'
        FILES = DEFAULT_CONFIG_PATHS + [
            os.path.join(DEFAULT_CONFIG_DIRECTORY, module_name, 'config.ini')
        ]

    return ModuleConfig


Instruction:
Can you generate the documentation for the following Python 3 function
def get_connection(module_name: str, connection: Optional[str] = None) -> str:
    # 1. Use given connection
    if connection is not None:
        return connection

    module_name = module_name.lower()
    module_config_cls = get_module_config_cls(module_name)
    module_config = module_config_cls.load()

    return module_config.connection or config.connection

Response: Returns the SQLAlchemy connection string for the given module.


Instruction:
Create a Python 3 function for
getting all Bio2BEL modules.

Response:
def get_modules() -> Mapping:
    """Get all Bio2BEL modules."""
    modules = {}

    for entry_point in iter_entry_points(group='bio2bel', name=None):
        entry = entry_point.name

        try:
            modules[entry] = entry_point.load()
        except VersionConflict as exc:
            log.warning('Version conflict in %s: %s', entry, exc)
            continue
        except UnknownExtra as exc:
            log.warning('Unknown extra in %s: %s', entry, exc)
            continue
        except ImportError as exc:
            log.exception('Issue with importing module %s: %s', entry, exc)
            continue

    return modules


Instruction:
Here you have a function in Python 3, explain what it does
def clear_cache(module_name: str, keep_database: bool = True) -> None:
    data_dir = get_data_dir(module_name)
    if not os.path.exists(data_dir):
        return
    for name in os.listdir(data_dir):
        if name in {'config.ini', 'cfg.ini'}:
            continue
        if name == 'cache.db' and keep_database:
            continue
        path = os.path.join(data_dir, name)
        if os.path.isdir(path):
            shutil.rmtree(path)
        else:
            os.remove(path)

        os.rmdir(data_dir)

Response: Clear all downloaded files and database files.


Instruction:
Write a Python 3 script to
add a populate command to main click function.

Response:
def add_cli_populate(main: click.Group) -> click.Group:  # noqa: D202
    """Add a ``populate`` command to main :mod:`click` function."""

    @main.command()
    @click.option('--reset', is_flag=True, help='Nuke database first')
    @click.option('--force', is_flag=True, help='Force overwrite if already populated')
    @click.pass_obj
    def populate(manager: AbstractManager, reset, force):
        """Populate the database."""
        if reset:
            click.echo('Deleting the previous instance of the database')
            manager.drop_all()
            click.echo('Creating new models')
            manager.create_all()

        if manager.is_populated() and not force:
            click.echo('Database already populated. Use --force to overwrite')
            sys.exit(0)

        manager.populate()

    return main


Instruction:
Implement a function in Python 3 to
add a drop command to main click function.

Response:
def add_cli_drop(main: click.Group) -> click.Group:  # noqa: D202
    """Add a ``drop`` command to main :mod:`click` function."""

    @main.command()
    @click.confirmation_option(prompt='Are you sure you want to drop the db?')
    @click.pass_obj
    def drop(manager):
        """Drop the database."""
        manager.drop_all()

    return main


Instruction:
How would you explain what the following Python 3 function does
def add_cli_cache(main: click.Group) -> click.Group:  # noqa: D202

    @main.group()
    def cache():
        """Manage cached data."""

    @cache.command()
    @click.pass_obj
    def locate(manager):
        """Print the location of the data directory."""
        data_dir = get_data_dir(manager.module_name)
        click.echo(data_dir)

    @cache.command()
    @click.pass_obj
    def ls(manager):
        """List files in the cache."""
        data_dir = get_data_dir(manager.module_name)

        for path in os.listdir(data_dir):
            click.echo(path)

    @cache.command()
    @click.pass_obj
    def clear(manager):
        """Clear all files from the cache."""
        clear_cache(manager.module_name)

    return main

Response: Add several commands to main click function for handling the cache.


Instruction:
Can you generate the documentation for the following Python 3 function
def add_cli_summarize(main: click.Group) -> click.Group:  # noqa: D202

    @main.command()
    @click.pass_obj
    def summarize(manager: AbstractManager):
        """Summarize the contents of the database."""
        if not manager.is_populated():
            click.secho(f'{manager.module_name} has not been populated', fg='red')
            sys.exit(1)

        for name, count in sorted(manager.summarize().items()):
            click.echo(f'{name.capitalize()}: {count}')

    return main

Response: Add a summarize command to main.


Instruction:
Here you have a function in Python 3, explain what it does
def create_all(self, check_first: bool = True):
        self._metadata.create_all(self.engine, checkfirst=check_first)

Response: Create the empty database.


Instruction:
Implement a Python 3 function for
dropping all tables from the database.

Response:
def drop_all(self, check_first: bool = True):
        """Drop all tables from the database.

        :param bool check_first: Defaults to True, only issue DROPs for tables confirmed to be
          present in the target database. Defers to :meth:`sqlalchemy.sql.schema.MetaData.drop_all`
        """
        self._metadata.drop_all(self.engine, checkfirst=check_first)
        self._store_drop()


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_cli(cls) -> click.Group:
        main = super().get_cli()

        cls._cli_add_populate(main)
        cls._cli_add_drop(main)
        cls._cli_add_cache(main)
        cls._cli_add_summarize(main)

        return main

Response: Get the click. Group to use as a command line interface.


Instruction:
Can you generate the documentation for the following Python 3 function
def label(labels=[], language='any', sortLabel=False):
    '''
    Provide a label for a list of labels.

    The items in the list of labels are assumed to be either instances of
    :class:`Label`, or dicts with at least the key `label` in them. These will
    be passed to the :func:`dict_to_label` function.

    This method tries to find a label by looking if there's
    a pref label for the specified language. If there's no pref label,
    it looks for an alt label. It disregards hidden labels.

    While matching languages, preference will be given to exact matches. But,
    if no exact match is present, an inexact match will be attempted. This might
    be because a label in language `nl-BE` is being requested, but only `nl` or
    even `nl-NL` is present. Similarly, when requesting `nl`, a label with
    language `nl-NL` or even `nl-Latn-NL` will also be considered,
    providing no label is present that has an exact match with the
    requested language.

    If language 'any' was specified, all labels will be considered,
    regardless of language.

    To find a label without a specified language, pass `None` as language.

    If a language or None was specified, and no label could be found, this
    method will automatically try to find a label in some other language.

    Finally, if no label could be found, None is returned.

    :param string language: The preferred language to receive the label in. This
        should be a valid IANA language tag.
    :param boolean sortLabel: Should sortLabels be considered or not? If True,
        sortLabels will be preferred over prefLabels. Bear in mind that these
        are still language dependent. So, it's possible to have a different
        sortLabel per language.
    :rtype: A :class:`Label` or `None` if no label could be found.
    '''
    if not labels:
        return None
    if not language:
        language = 'und'
    labels = [dict_to_label(l) for l in labels]
    l = False
    if sortLabel:
        l = find_best_label_for_type(labels, language, 'sortLabel')
    if not l:
        l = find_best_label_for_type(labels, language, 'prefLabel')
    if not l:
        l = find_best_label_for_type(labels, language, 'altLabel')
    if l:
        return l
    else:
        return label(labels, 'any', sortLabel) if language != 'any' else None

Response: Returns a new IANA label for a list of labels.


Instruction:
Can you tell what is the following Python 3 function doing
def find_best_label_for_type(labels, language, labeltype):
    '''
    Find the best label for a certain labeltype.

    :param list labels: A list of :class:`Label`.
    :param str language: An IANA language string, eg. `nl` or `nl-BE`.
    :param str labeltype: Type of label to look for, eg. `prefLabel`.
    '''
    typelabels = [l for l in labels if l.type == labeltype]
    if not typelabels:
        return False
    if language == 'any':
        return typelabels[0]
    exact = filter_labels_by_language(typelabels, language)
    if exact:
        return exact[0]
    inexact = filter_labels_by_language(typelabels, language, True)
    if inexact:
        return inexact[0]
    return False

Response: Find the best label for a certain labeltype.


Instruction:
Can you write a function in Python 3 where it
filters a list of labels leaving only labels of a certain language.

Response:
def filter_labels_by_language(labels, language, broader=False):
    '''
    Filter a list of labels, leaving only labels of a certain language.

    :param list labels: A list of :class:`Label`.
    :param str language: An IANA language string, eg. `nl` or `nl-BE`.
    :param boolean broader: When true, will also match `nl-BE` when filtering
        on `nl`. When false, only exact matches are considered.
    '''
    if language == 'any':
        return labels
    if broader:
        language = tags.tag(language).language.format
        return [l for l in labels if tags.tag(l.language).language.format == language]
    else:
        language = tags.tag(language).format
        return [l for l in labels if tags.tag(l.language).format == language]


Instruction:
Write a Python 3 script for
transforming a dict with keys label type and language into a .

Response:
def dict_to_label(dict):
    '''
    Transform a dict with keys `label`, `type` and `language` into a
    :class:`Label`.

    Only the `label` key is mandatory. If `type` is not present, it will
    default to `prefLabel`. If `language` is not present, it will default
    to `und`.

    If the argument passed is not a dict, this method just
    returns the argument.
    '''
    try:
        return Label(
            dict['label'],
            dict.get('type', 'prefLabel'),
            dict.get('language', 'und')
        )
    except (KeyError, AttributeError, TypeError):
        return dict


Instruction:
Write a Python 3 script for
transforming a dict with keys note type language and markup into a

Response:
def dict_to_note(dict):
    '''
    Transform a dict with keys `note`, `type` and `language` into a
    :class:`Note`.

    Only the `note` key is mandatory. If `type` is not present, it will
    default to `note`. If `language` is not present, it will default to `und`.
    If `markup` is not present it will default to `None`.

    If the argument passed is already a :class:`Note`, this method just returns
    the argument.
    '''
    if isinstance(dict, Note):
        return dict
    return Note(
        dict['note'],
        dict.get('type', 'note'),
        dict.get('language', 'und'),
        dict.get('markup')
    )


Instruction:
Implement a Python 3 function for
transforming a dict with key citation into a Source.

Response:
def dict_to_source(dict):
    '''
    Transform a dict with key 'citation' into a :class:`Source`.

    If the argument passed is already a :class:`Source`, this method just
    returns the argument.
    '''

    if isinstance(dict, Source):
        return dict
    return Source(
        dict['citation'],
        dict.get('markup')
    )


Instruction:
Write a Python 3 function that can
return a single sortkey for this conceptscheme.

Response:
def _sortkey(self, key='uri', language='any'):
        '''
        Provide a single sortkey for this conceptscheme.

        :param string key: Either `uri`, `label` or `sortlabel`.
        :param string language: The preferred language to receive the label in
            if key is `label` or `sortlabel`. This should be a valid IANA language tag.
        :rtype: :class:`str`
        '''
        if key == 'uri':
            return self.uri
        else:
            l = label(self.labels, language, key == 'sortlabel')
            return l.label.lower() if l else ''


Instruction:
How would you implement a function in Python 3 that
iterates over instantiated managers.

Response:
def _iterate_managers(connection, skip):
    """Iterate over instantiated managers."""
    for idx, name, manager_cls in _iterate_manage_classes(skip):
        if name in skip:
            continue

        try:
            manager = manager_cls(connection=connection)
        except TypeError as e:
            click.secho(f'Could not instantiate {name}: {e}', fg='red')
        else:
            yield idx, name, manager


Instruction:
Explain what the following Python 3 code does
def summarize(connection, skip):
    for idx, name, manager in _iterate_managers(connection, skip):
        click.secho(name, fg='cyan', bold=True)
        if not manager.is_populated():
            click.echo('👎 unpopulated')
            continue

        if isinstance(manager, BELNamespaceManagerMixin):
            click.secho(f'Terms: {manager._count_model(manager.namespace_model)}', fg='green')

        if isinstance(manager, BELManagerMixin):
            try:
                click.secho(f'Relations: {manager.count_relations()}', fg='green')
            except TypeError as e:
                click.secho(str(e), fg='red')
        for field_name, count in sorted(manager.summarize().items()):
            click.echo(
                click.style('=> ', fg='white', bold=True) + f"{field_name.replace('_', ' ').capitalize()}: {count}"
            )

Response: Summarize all available resources.


Instruction:
Here you have a function in Python 3, explain what it does
def sheet(connection, skip, file: TextIO):
    from tabulate import tabulate
    header = ['', 'Name', 'Description', 'Terms', 'Relations']
    rows = []

    for i, (idx, name, manager) in enumerate(_iterate_managers(connection, skip), start=1):
        try:
            if not manager.is_populated():
                continue
        except AttributeError:
            click.secho(f'{name} does not implement is_populated', fg='red')
            continue

        terms, relations = None, None
        if isinstance(manager, BELNamespaceManagerMixin):
            terms = manager._count_model(manager.namespace_model)

        if isinstance(manager, BELManagerMixin):
            try:
                relations = manager.count_relations()
            except TypeError as e:
                relations = str(e)

        rows.append((i, name, manager.__doc__.split('\n')[0].strip().strip('.'), terms, relations))

    print(tabulate(
        rows,
        headers=header,
        # tablefmt="fancy_grid",
    ))

Response: Generate a summary sheet.


Instruction:
How would you explain what the following Python 3 function does
def write(connection, skip, directory, force):
    os.makedirs(directory, exist_ok=True)
    from .manager.namespace_manager import BELNamespaceManagerMixin
    for idx, name, manager in _iterate_managers(connection, skip):
        if not (isinstance(manager, AbstractManager) and isinstance(manager, BELNamespaceManagerMixin)):
            continue
        click.secho(name, fg='cyan', bold=True)
        if force:
            try:
                click.echo(f'dropping')
                manager.drop_all()
                click.echo('clearing cache')
                clear_cache(name)
                click.echo('populating')
                manager.populate()
            except Exception:
                click.secho(f'{name} failed', fg='red')
                continue

        try:
            r = manager.write_directory(directory)
        except TypeError as e:
            click.secho(f'error with {name}: {e}'.rstrip(), fg='red')
        else:
            if not r:
                click.echo('no update')

Response: Write a BEL namespace names to terminology store.


Instruction:
Can you generate the documentation for the following Python 3 function
def write(connection, skip, directory, force):
    os.makedirs(directory, exist_ok=True)
    from .manager.bel_manager import BELManagerMixin
    import pybel
    for idx, name, manager in _iterate_managers(connection, skip):
        if not isinstance(manager, BELManagerMixin):
            continue
        click.secho(name, fg='cyan', bold=True)
        path = os.path.join(directory, f'{name}.bel.pickle')
        if os.path.exists(path) and not force:
            click.echo('👍 already exported')
            continue

        if not manager.is_populated():
            click.echo('👎 unpopulated')
        else:
            graph = manager.to_bel()
            pybel.to_pickle(graph, path)
            pybel.to_json_path(graph, os.path.join(directory, f'{name}.bel.json'))

Response: Write all BEL objects in a directory.


Instruction:
Can you tell what is the following Python 3 function doing
def web(connection, host, port):
    from bio2bel.web.application import create_application
    app = create_application(connection=connection)
    app.run(host=host, port=port)

Response: Run a combine web interface.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def add_cli_to_bel(main: click.Group) -> click.Group:  # noqa: D202

    @main.command()
    @click.option('-o', '--output', type=click.File('w'), default=sys.stdout)
    @click.option('-f', '--fmt', default='bel', show_default=True, help='BEL export format')
    @click.pass_obj
    def write(manager: BELManagerMixin, output: TextIO, fmt: str):
        """Write as BEL Script."""
        graph = manager.to_bel()
        graph.serialize(file=output, fmt=fmt)
        click.echo(graph.summary_str())

    return main

Response: Add several command to main click function related to export to BEL.


Instruction:
How would you implement a function in Python 3 that
adds several commands to main click function related to export to BEL Commons.

Response:
def add_cli_upload_bel(main: click.Group) -> click.Group:  # noqa: D202
    """Add several command to main :mod:`click` function related to export to BEL."""

    @main.command()
    @host_option
    @click.pass_obj
    def upload(manager: BELManagerMixin, host: str):
        """Upload BEL to BEL Commons."""
        graph = manager.to_bel()
        pybel.to_web(graph, host=host, public=True)

    return main


Instruction:
Write a Python 3 function for
counting the number of BEL relations generated.

Response:
def count_relations(self) -> int:
        """Count the number of BEL relations generated."""
        if self.edge_model is ...:
            raise Bio2BELMissingEdgeModelError('edge_edge model is undefined/count_bel_relations is not overridden')
        elif isinstance(self.edge_model, list):
            return sum(self._count_model(m) for m in self.edge_model)
        else:
            return self._count_model(self.edge_model)


Instruction:
Explain what the following Python 3 code does
def to_indra_statements(self, *args, **kwargs):
        graph = self.to_bel(*args, **kwargs)
        return to_indra_statements(graph)

Response: Dump this object as INDRA statements.


Instruction:
Can you generate the documentation for the following Python 3 function
def get_cli(cls) -> click.Group:
        main = super().get_cli()

        @main.group()
        def bel():
            """Manage BEL."""

        cls._cli_add_to_bel(bel)
        cls._cli_add_upload_bel(bel)

        return main

Response: Get a click. Group that adds added BEL commands to the BEL.


Instruction:
Explain what the following Python 3 code does
def _convert_coordinatelist(input_obj):
    cdl = pgmagick.CoordinateList()
    for obj in input_obj:
        cdl.append(pgmagick.Coordinate(obj[0], obj[1]))
    return cdl

Response: convert from list or tuple object to pgmagick. CoordinateList


Instruction:
Can you write a function in Python 3 where it
converts from list or tuple object to pgmagick. VPathList

Response:
def _convert_vpathlist(input_obj):
    """convert from 'list' or 'tuple' object to pgmagick.VPathList.

    :type input_obj: list or tuple
    """
    vpl = pgmagick.VPathList()
    for obj in input_obj:
        # FIXME
        obj = pgmagick.PathMovetoAbs(pgmagick.Coordinate(obj[0], obj[1]))
        vpl.append(obj)
    return vpl


Instruction:
Can you generate the documentation for the following Python 3 function
def get_exif_info(self):
        _dict = {}
        for tag in _EXIF_TAGS:
            ret = self.img.attribute("EXIF:%s" % tag)
            if ret and ret != 'unknown':
                _dict[tag] = ret
        return _dict

Response: return exif - tag dict


Instruction:
Write a Python 3 script to
draw a Bezier curve.

Response:
def bezier(self, points):
        """Draw a Bezier-curve.

        :param points: ex.) ((5, 5), (6, 6), (7, 7))
        :type points: list
        """
        coordinates = pgmagick.CoordinateList()
        for point in points:
            x, y = float(point[0]), float(point[1])
            coordinates.append(pgmagick.Coordinate(x, y))
        self.drawer.append(pgmagick.DrawableBezier(coordinates))


Instruction:
Can you create a Python 3 function that
adds a color to the drawing

Response:
def color(self, x, y, paint_method):
        """
        :param paint_method: 'point' or 'replace' or 'floodfill' or
                             'filltoborder' or 'reset'
        :type paint_method: str or pgmagick.PaintMethod
        """
        paint_method = _convert_paintmethod(paint_method)
        color = pgmagick.DrawableColor(x, y, paint_method)
        self.drawer.append(color)


Instruction:
Write a Python 3 function that can
add an ellipse to the drawable

Response:
def ellipse(self, org_x, org_y, radius_x, radius_y, arc_start, arc_end):
        """
        :param org_x: origination x axis
        :param org_y: origination y axis
        :param radius_x: radius x axis
        :param radius_y: radius y axis
        :param arc_start: arc start angle
        :param arc_end: arc end angle
        """
        ellipse = pgmagick.DrawableEllipse(float(org_x), float(org_y),
                                           float(radius_x), float(radius_y),
                                           float(arc_start), float(arc_end))
        self.drawer.append(ellipse)


Instruction:
Create a Python 3 function to
add an opacity to the drawable

Response:
def fill_opacity(self, opacity):
        """
        :param opacity: 0.0 ~ 1.0
        """
        opacity = pgmagick.DrawableFillOpacity(float(opacity))
        self.drawer.append(opacity)


Instruction:
Make a summary of the following Python 3 code
def matte(self, x, y, paint_method):
        paint_method = _convert_paintmethod(paint_method)
        self.drawer.append(pgmagick.DrawableMatte(x, y, paint_method))

Response: add a new darker drawable to the list of available drawers


Instruction:
Create a Python 3 function to
scale Draw Object :param x: 0.0 ~ 1.0 :param y: 0.0 ~ 1.0

Response:
def scaling(self, x, y):
        """Scaling Draw Object

        :param x: 0.0 ~ 1.0
        :param y: 0.0 ~ 1.0
        """
        self.drawer.append(pgmagick.DrawableScaling(float(x), float(y)))


Instruction:
How would you implement a function in Python 3 that
strokes antialias on the current node

Response:
def stroke_antialias(self, flag=True):
        """stroke antialias

        :param flag: True or False. (default is True)
        :type flag: bool
        """
        antialias = pgmagick.DrawableStrokeAntialias(flag)
        self.drawer.append(antialias)


Instruction:
Given the following Python 3 function, write the documentation
def stroke_linecap(self, linecap):
        linecap = getattr(pgmagick.LineCap, "%sCap" % linecap.title())
        linecap = pgmagick.DrawableStrokeLineCap(linecap)
        self.drawer.append(linecap)

Response: set to stroke linecap. linecap is defined as a string


Instruction:
Write a Python 3 function for
setting to stroke linejoin. linejoin can be undefined miter round bevel

Response:
def stroke_linejoin(self, linejoin):
        """set to stroke linejoin.

        :param linejoin: 'undefined', 'miter', 'round', 'bevel'
        :type linejoin: str
        """
        linejoin = getattr(pgmagick.LineJoin, "%sJoin" % linejoin.title())
        linejoin = pgmagick.DrawableStrokeLineJoin(linejoin)
        self.drawer.append(linejoin)


Instruction:
Given the following Python 3 function, write the documentation
def text_antialias(self, flag=True):
        antialias = pgmagick.DrawableTextAntialias(flag)
        self.drawer.append(antialias)

Response: text antialias is a wrapper around pgmagick. DrawableTextAntialias


Instruction:
Here you have a function in Python 3, explain what it does
def text_decoration(self, decoration):
        if decoration.lower() == 'linethrough':
            d = pgmagick.DecorationType.LineThroughDecoration
        else:
            decoration_type_string = "%sDecoration" % decoration.title()
            d = getattr(pgmagick.DecorationType, "%s" % decoration_type_string)
        decoration = pgmagick.DrawableTextDecoration(d)
        self.drawer.append(decoration)

Response:
text decoration
            is no underline overline linethrough is no


Instruction:
Explain what the following Python 3 code does
def get_version_from_pc(search_dirs, target):
    for dirname in search_dirs:
        for root, dirs, files in os.walk(dirname):
            for f in files:
                if f == target:
                    file_path = os.path.join(root, target)
                    _tmp = _grep("Version: ", file_path)
                    version = _tmp.split()[1]
                    print("Found version %s in file %s" % (version, file_path))
                    return version

Response: get version from pc file


Instruction:
Implement a Python 3 function for
returning whether given library version supports given API version.

Response:
def library_supports_api(library_version, api_version, different_major_breaks_support=True):
    """
    Returns whether api_version is supported by given library version.
    E. g.  library_version (1,3,21) returns True for api_version (1,3,21), (1,3,19), (1,3,'x'), (1,2,'x'), (1, 'x')
           False for (1,3,24), (1,4,'x'), (2,'x')

    different_major_breaks_support - if enabled and library and api major versions are different always return False
           ex) with library_version (2,0,0) and for api_version(1,3,24) returns False if enabled, True if disabled
    """
    assert isinstance(library_version, (tuple, list))  # won't work with e.g. generators
    assert len(library_version) == 3
    sequence_type = type(library_version)  # assure we will compare same types
    api_version = sequence_type(0 if num == 'x' else num for num in api_version)
    if different_major_breaks_support and library_version[0] != api_version[0]:
        return False
    assert len(api_version) <= 3     # otherwise following comparision won't work as intended, e.g. (2, 0, 0) > (2, 0, 0, 0)
    return library_version >= api_version


Instruction:
How would you implement a function in Python 3 that
returns a list of accepting roles.

Response:
def get_roles_request(request):
    """Returns a list of accepting roles."""
    uuid_ = request.matchdict['uuid']
    user_id = request.matchdict.get('uid')

    args = [uuid_]
    if user_id is not None:
        fmt_conditional = "AND user_id = %s"
        args.append(user_id)
    else:
        fmt_conditional = ""

    with db_connect() as db_conn:
        with db_conn.cursor() as cursor:
            cursor.execute("""\
SELECT row_to_json(combined_rows) FROM (
SELECT uuid, user_id AS uid, role_type AS role, accepted AS has_accepted
FROM role_acceptances AS la
WHERE uuid = %s {}
ORDER BY user_id ASC, role_type ASC
) as combined_rows""".format(fmt_conditional), args)
            acceptances = [r[0] for r in cursor.fetchall()]

            if not acceptances:
                if user_id is not None:
                    raise httpexceptions.HTTPNotFound()
                else:
                    cursor.execute("""\
SELECT TRUE FROM document_controls WHERE uuid = %s""", (uuid_,))
                    try:
                        cursor.fetchone()[0]
                    except TypeError:  # NoneType
                        raise httpexceptions.HTTPNotFound()

    resp_value = acceptances
    if user_id is not None:
        resp_value = acceptances[0]
    return resp_value


Instruction:
Can you tell what is the following Python 3 function doing
def delete_roles_request(request):
    uuid_ = request.matchdict['uuid']

    posted_roles = request.json
    with db_connect() as db_conn:
        with db_conn.cursor() as cursor:
            remove_role_requests(cursor, uuid_, posted_roles)

    resp = request.response
    resp.status_int = 200
    return resp

Response: Submission to remove a role acceptance request.


Instruction:
Can you create a Python 3 function that
returns the ACL for the given content identified by uuid.

Response:
def get_acl(request):
    """Returns the ACL for the given content identified by ``uuid``."""
    uuid_ = request.matchdict['uuid']

    with db_connect() as db_conn:
        with db_conn.cursor() as cursor:
            cursor.execute("""\
SELECT TRUE FROM document_controls WHERE uuid = %s""", (uuid_,))
            try:
                # Check that it exists
                cursor.fetchone()[0]
            except TypeError:
                raise httpexceptions.HTTPNotFound()
            cursor.execute("""\
SELECT row_to_json(combined_rows) FROM (
SELECT uuid, user_id AS uid, permission
FROM document_acl AS acl
WHERE uuid = %s
ORDER BY user_id ASC, permission ASC
) as combined_rows""", (uuid_,))
            acl = [r[0] for r in cursor.fetchall()]

    return acl


Instruction:
Explain what the following Python 3 code does
def post_acl_request(request):
    uuid_ = request.matchdict['uuid']

    posted = request.json
    permissions = [(x['uid'], x['permission'],) for x in posted]
    with db_connect() as db_conn:
        with db_conn.cursor() as cursor:
            cursor.execute("""\
SELECT TRUE FROM document_controls WHERE uuid = %s::UUID""", (uuid_,))
            try:
                # Check that it exists
                cursor.fetchone()[0]
            except TypeError:
                if request.has_permission('publish.create-identifier'):
                    cursor.execute("""\
INSERT INTO document_controls (uuid) VALUES (%s)""", (uuid_,))
                else:
                    raise httpexceptions.HTTPNotFound()
            upsert_acl(cursor, uuid_, permissions)

    resp = request.response
    resp.status_int = 202
    return resp

Response: Submission to create an ACL.


Instruction:
Can you generate the documentation for the following Python 3 function
def delete_acl_request(request):
    uuid_ = request.matchdict['uuid']

    posted = request.json
    permissions = [(x['uid'], x['permission'],) for x in posted]
    with db_connect() as db_conn:
        with db_conn.cursor() as cursor:
            remove_acl(cursor, uuid_, permissions)

    resp = request.response
    resp.status_int = 200
    return resp

Response: Submission to remove an ACL.


Instruction:
Given the following Python 3 function, write the documentation
def processor():  # pragma: no cover
    registry = get_current_registry()
    settings = registry.settings
    connection_string = settings[CONNECTION_STRING]
    channels = _get_channels(settings)

    # Code adapted from
    # http://initd.org/psycopg/docs/advanced.html#asynchronous-notifications
    with psycopg2.connect(connection_string) as conn:
        conn.set_isolation_level(ISOLATION_LEVEL_AUTOCOMMIT)

        with conn.cursor() as cursor:
            for channel in channels:
                cursor.execute('LISTEN {}'.format(channel))
                logger.debug('Waiting for notifications on channel "{}"'
                             .format(channel))

        registry.notify(ChannelProcessingStartUpEvent())

        rlist = [conn]  # wait until ready for reading
        wlist = []  # wait until ready for writing
        xlist = []  # wait for an "exceptional condition"
        timeout = 5

        while True:
            if select.select(rlist, wlist, xlist, timeout) != ([], [], []):
                conn.poll()
                while conn.notifies:
                    notif = conn.notifies.pop(0)
                    logger.debug('Got NOTIFY: pid={} channel={} payload={}'
                                 .format(notif.pid, notif.channel,
                                         notif.payload))
                    event = create_pg_notify_event(notif)
                    try:
                        registry.notify(event)
                    except Exception:
                        logger.exception('Logging an uncaught exception')

Response: This function is used to run the asynchronous notifications on the configured channels.


Instruction:
Create a Python 3 function to
give a dbapi cursor lookup all the api keys and their information.

Response:
def lookup_api_key_info():
    """Given a dbapi cursor, lookup all the api keys and their information."""
    info = {}
    with db_connect() as conn:
        with conn.cursor() as cursor:
            cursor.execute(ALL_KEY_INFO_SQL_STMT)
            for row in cursor.fetchall():
                id, key, name, groups = row
                user_id = "api_key:{}".format(id)
                info[key] = dict(id=id, user_id=user_id,
                                 name=name, groups=groups)
    return info


Instruction:
Given the following Python 3 function, write the documentation
def includeme(config):
    api_key_authn_policy = APIKeyAuthenticationPolicy()
    config.include('openstax_accounts')
    openstax_authn_policy = config.registry.getUtility(
        IOpenstaxAccountsAuthenticationPolicy)

    # Set up api & user authentication policies.
    policies = [api_key_authn_policy, openstax_authn_policy]
    authn_policy = MultiAuthenticationPolicy(policies)
    config.set_authentication_policy(authn_policy)

    # Set up the authorization policy.
    authz_policy = ACLAuthorizationPolicy()
    config.set_authorization_policy(authz_policy)

Response: Configuration include fuction for this module


Instruction:
Explain what the following Python 3 code does
def expandvars_dict(settings):
    return dict(
        (key, os.path.expandvars(value))
        for key, value in settings.iteritems()
    )

Response: Expands all environment variables in a settings dictionary.


Instruction:
Write a Python 3 script to
initialize the Sentry service with the current app s Sentry_DSN.

Response:
def initialize_sentry_integration():  # pragma: no cover
    """\
    Used to optionally initialize the Sentry service with this app.
    See https://docs.sentry.io/platforms/python/pyramid/

    """
    # This function is not under coverage because it is boilerplate
    # from the Sentry documentation.
    try:
        import sentry_sdk
        from sentry_sdk.integrations.pyramid import PyramidIntegration
        from sentry_sdk.integrations.celery import CeleryIntegration
    except ImportError:
        warnings.warn(
            "Sentry is not configured because the Sentry SDK "
            "(sentry_sdk package) is not installed",
            UserWarning,
        )
        return  # bail out early

    try:
        dsn = os.environ['SENTRY_DSN']
    except KeyError:
        warnings.warn(
            "Sentry is not configured because SENTRY_DSN "
            "was not supplied.",
            UserWarning,
        )
    else:
        sentry_sdk.init(
            dsn=dsn,
            integrations=[PyramidIntegration(), CeleryIntegration()],
        )


Instruction:
Can you tell what is the following Python 3 function doing
def task(**kwargs):

    def wrapper(wrapped):

        def callback(scanner, name, obj):
            celery_app = scanner.config.registry.celery_app
            celery_app.task(**kwargs)(obj)

        venusian.attach(wrapped, callback)
        return wrapped

    return wrapper

Response: A function task decorator used in place of celery_app. task.


Instruction:
Here you have a function in Python 3, explain what it does
def _make_celery_app(config):
    # Tack the pyramid config on the celery app for later use.
    config.registry.celery_app.conf['pyramid_config'] = config
    return config.registry.celery_app

Response: This function creates a celery app that is used to run pyramid tasks.


Instruction:
Write a Python 3 script for
processing post - publication events coming out of the database.

Response:
def post_publication_processing(event, cursor):
    """Process post-publication events coming out of the database."""
    module_ident, ident_hash = event.module_ident, event.ident_hash

    celery_app = get_current_registry().celery_app

    # Check baking is not already queued.
    cursor.execute('SELECT result_id::text '
                   'FROM document_baking_result_associations '
                   'WHERE module_ident = %s', (module_ident,))
    for result in cursor.fetchall():
        state = celery_app.AsyncResult(result[0]).state
        if state in ('QUEUED', 'STARTED', 'RETRY'):
            logger.debug('Already queued module_ident={} ident_hash={}'.format(
                module_ident, ident_hash))
            return

    logger.debug('Queued for processing module_ident={} ident_hash={}'.format(
        module_ident, ident_hash))
    recipe_ids = _get_recipe_ids(module_ident, cursor)
    update_module_state(cursor, module_ident, 'processing', recipe_ids[0])
    # Commit the state change before preceding.
    cursor.connection.commit()

    # Start of task
    # FIXME Looking up the task isn't the most clear usage here.
    task_name = 'cnxpublishing.subscribers.baking_processor'
    baking_processor = celery_app.tasks[task_name]
    result = baking_processor.delay(module_ident, ident_hash)
    baking_processor.backend.store_result(result.id, None, 'QUEUED')

    # Save the mapping between a celery task and this event.
    track_baking_proc_state(result, module_ident, cursor)


Instruction:
Explain what the following Python 3 code does
def parse_archive_uri(uri):
    parsed = urlparse(uri)
    path = parsed.path.rstrip('/').split('/')
    ident_hash = path[-1]
    ident_hash = unquote(ident_hash)
    return ident_hash

Response: Given an archive URI parse to a split ident - hash.


Instruction:
Make a summary of the following Python 3 code
def declare_api_routes(config):
    add_route = config.add_route
    add_route('get-content', '/contents/{ident_hash}')
    add_route('get-resource', '/resources/{hash}')

    # User actions API
    add_route('license-request', '/contents/{uuid}/licensors')
    add_route('roles-request', '/contents/{uuid}/roles')
    add_route('acl-request', '/contents/{uuid}/permissions')

    # Publishing API
    add_route('publications', '/publications')
    add_route('get-publication', '/publications/{id}')
    add_route('publication-license-acceptance',
              '/publications/{id}/license-acceptances/{uid}')
    add_route('publication-role-acceptance',
              '/publications/{id}/role-acceptances/{uid}')
    # TODO (8-May-12017) Remove because the term collate is being phased out.
    add_route('collate-content', '/contents/{ident_hash}/collate-content')
    add_route('bake-content', '/contents/{ident_hash}/baked')

    # Moderation routes
    add_route('moderation', '/moderations')
    add_route('moderate', '/moderations/{id}')
    add_route('moderation-rss', '/feeds/moderations.rss')

    # API Key routes
    add_route('api-keys', '/api-keys')
    add_route('api-key', '/api-keys/{id}')

Response: Declare the routes for the API.


Instruction:
Explain what the following Python 3 code does
def declare_browsable_routes(config):
    # This makes our routes slashed, which is good browser behavior.
    config.add_notfound_view(default_exceptionresponse_view,
                             append_slash=True)

    add_route = config.add_route
    add_route('admin-index', '/a/')
    add_route('admin-moderation', '/a/moderation/')
    add_route('admin-api-keys', '/a/api-keys/')
    add_route('admin-add-site-messages', '/a/site-messages/',
              request_method='GET')
    add_route('admin-add-site-messages-POST', '/a/site-messages/',
              request_method='POST')
    add_route('admin-delete-site-messages', '/a/site-messages/',
              request_method='DELETE')
    add_route('admin-edit-site-message', '/a/site-messages/{id}/',
              request_method='GET')
    add_route('admin-edit-site-message-POST', '/a/site-messages/{id}/',
              request_method='POST')

    add_route('admin-content-status', '/a/content-status/')
    add_route('admin-content-status-single', '/a/content-status/{uuid}')

    add_route('admin-print-style', '/a/print-style/')
    add_route('admin-print-style-single', '/a/print-style/{style}')

Response: Declare the routes that can be browsed by users.


Instruction:
Explain what the following Python 3 code does
def _formatter_callback_factory():  # pragma: no cover
    includes = []
    exercise_url_template = '{baseUrl}/api/exercises?q={field}:"{{itemCode}}"'
    settings = get_current_registry().settings
    exercise_base_url = settings.get('embeddables.exercise.base_url', None)
    exercise_matches = [match.split(',', 1) for match in aslist(
        settings.get('embeddables.exercise.match', ''), flatten=False)]
    exercise_token = settings.get('embeddables.exercise.token', None)
    mathml_url = settings.get('mathmlcloud.url', None)
    memcache_servers = settings.get('memcache_servers')
    if memcache_servers:
        memcache_servers = memcache_servers.split()
    else:
        memcache_servers = None

    if exercise_base_url and exercise_matches:
        mc_client = None
        if memcache_servers:
            mc_client = memcache.Client(memcache_servers, debug=0)
        for (exercise_match, exercise_field) in exercise_matches:
            template = exercise_url_template.format(
                baseUrl=exercise_base_url, field=exercise_field)
            includes.append(exercise_callback_factory(exercise_match,
                                                      template,
                                                      mc_client,
                                                      exercise_token,
                                                      mathml_url))
    return includes

Response: Returns a list of includes to be given to cnxepub. collation. collate.


Instruction:
How would you code a function in Python 3 to
bake the contents and persist those changes alongside the published content.

Response:
def bake(binder, recipe_id, publisher, message, cursor):
    """Given a `Binder` as `binder`, bake the contents and
    persist those changes alongside the published content.

    """
    recipe = _get_recipe(recipe_id, cursor)
    includes = _formatter_callback_factory()
    binder = collate_models(binder, ruleset=recipe, includes=includes)

    def flatten_filter(model):
        return (isinstance(model, cnxepub.CompositeDocument) or
                (isinstance(model, cnxepub.Binder) and
                 model.metadata.get('type') == 'composite-chapter'))

    def only_documents_filter(model):
        return isinstance(model, cnxepub.Document) \
            and not isinstance(model, cnxepub.CompositeDocument)

    for doc in cnxepub.flatten_to(binder, flatten_filter):
        publish_composite_model(cursor, doc, binder, publisher, message)

    for doc in cnxepub.flatten_to(binder, only_documents_filter):
        publish_collated_document(cursor, doc, binder)

    tree = cnxepub.model_to_tree(binder)
    publish_collated_tree(cursor, tree)

    return []


Instruction:
Given the following Python 3 function, write the documentation
def volcano(differential_dfs, title='Axial Volcano Plot', scripts_mode="CDN", data_mode="directory",
            organism="human", q_value_column_name="q", log2FC_column_name="logFC",
            output_dir=".", filename="volcano.html", version=this_version):
    """
    Arguments:
        differential_dfs (dict or pandas.DataFrame): python dict of names to pandas dataframes, or a single dataframe, indexed by gene symbols which must have columns named log2FC and qval.
        title (str): The title of the plot (to be embedded in the html).
        scripts_mode (str): Choose from [`"CDN"`, `"directory"`, `"inline"`]:

            - `"CDN"` compiles a single HTML page with links to scripts hosted on a CDN,

            - `"directory"` compiles a directory with all scripts locally cached,

            - `"inline"` compiles a single HTML file with all scripts/styles inlined.

        data_mode (str): Choose from ["directory", "inline"]:

            - "directory" compiles a directory with all data locally cached,

            - "inline" compiles a single HTML file with all data inlined.

        organism (str): `"human"` or `"mouse"`
        q_value_column_name (str):
        log2FC_column_name (str):
        output_dir (str): the directory in which to output the file
        filename (str): the filename of the output file
        version (str): the version of the javascripts to use.
            Leave the default to pin the version, or choose "latest" to get updates,
            or choose part of the version string to get minor updates.
    Returns:
        Path: The filepath which the html was outputted to.
    """

    output_dir = Path(output_dir)
    output_dir.mkdir(exist_ok=True, parents=True)

    # Data   =======================

    if isinstance(differential_dfs, pd.DataFrame):
        differential_dfs = {'differential': differential_dfs}

    for name, df in differential_dfs.items():
        df = df[[q_value_column_name, log2FC_column_name]]
        df.columns = ['q', 'logFC']
        df = df.round(2)
        # TODO drop all zero rows
        _verify_differential_df(df)

        del differential_dfs[name]
        differential_dfs[_sanitize(name)] = df

    names_and_differentials = f"var names_and_differentials = { '{'+ ','.join([_quote(name)+': '+df.to_json(orient='index') for name, df in differential_dfs.items()]) +'}' };"

    data_block = _data_block(data_mode, [('names_and_differentials', names_and_differentials)], output_dir, include_gene_sets=False, organism=organism)

    # Scripts =======================

    scripts = third_party_scripts + [CDN_url(version)+"js/util.js", CDN_url(version)+"js/GOrilla.js", CDN_url(version)+"js/volcano.js"]

    scripts_block = _scripts_block(scripts, scripts_mode, output_dir)

    html = templateEnv.get_template('volcano.html.j2').render(title=title, scripts_block=scripts_block+'\n'+data_block, organism="HOMO_SAPIENS")

    (output_dir / filename).write_text(html)

    return (output_dir / filename).resolve()

Response: Generate a new volcano file from a differential plot.


Instruction:
Write a Python 3 function that can
generate a heatmap from a dataframe indexed by genes and sample attributes.

Response:
def heatmap(genes_by_samples_matrix, sample_attributes, title='Axial Heatmap', scripts_mode="CDN", data_mode="directory",
            organism="human", separate_zscore_by=["system"],
            output_dir=".", filename="heatmap.html", version=this_version):
    """
    Arguments:
        genes_by_samples_matrix (pandas.DataFrame): dataframe indexed by genes, columns are samples
        sample_attributes (pandas.DataFrame): dataframe indexed by samples, columns are sample attributes (e.g. classes)
        title (str): The title of the plot (to be embedded in the html).
        scripts_mode (str): Choose from [`"CDN"`, `"directory"`, `"inline"`]:

            - `"CDN"` compiles a single HTML page with links to scripts hosted on a CDN,

            - `"directory"` compiles a directory with all scripts locally cached,

            - `"inline"` compiles a single HTML file with all scripts/styles inlined.

        data_mode (str): Choose from ["directory", "inline"]:

            - "directory" compiles a directory with all data locally cached,

            - "inline" compiles a single HTML file with all data inlined.

        organism (str): `"human"` or `"mouse"`
        separate_zscore_by (list):
        output_dir (str): the directory in which to output the file
        filename (str): the filename of the output file
        version (str): the version of the javascripts to use.
            Leave the default to pin the version, or choose "latest" to get updates,
            or choose part of the version string to get minor updates.
    Returns:
        Path: The filepath which the html was outputted to.
    """

    output_dir = Path(output_dir)
    output_dir.mkdir(exist_ok=True, parents=True)

    # Data   =======================

    _verify_sample_by_genes_matrix(genes_by_samples_matrix)
    _verify_sample_attributes(genes_by_samples_matrix, sample_attributes)
    genes_by_samples_matrix = genes_by_samples_matrix.round(2)
    # TODO drop all zero rows

    matrix = f"var matrix = {genes_by_samples_matrix.to_json(orient='columns')};"
    classes = f"var classes = {sample_attributes.to_json(orient='index')};"

    data_block = _data_block(data_mode, [('matrix', matrix), ('classes', classes)], output_dir, organism=organism)

    # Scripts =======================

    scripts = third_party_scripts + [CDN_url(version)+"js/util.js", CDN_url(version)+"js/reorder.js", CDN_url(version)+"js/heatmap.js"]

    scripts_block = _scripts_block(scripts, scripts_mode, output_dir)

    html = templateEnv.get_template('heatmap.html.j2').render(title=title, scripts_block=scripts_block+'\n'+data_block, separate_zscore_by=separate_zscore_by)

    (output_dir / filename).write_text(html)

    return (output_dir / filename).resolve()


Instruction:
Can you tell what is the following Python 3 function doing
def graph(networkx_graph, title='Axial Graph Visualization', scripts_mode="CDN", data_mode="directory",
          output_dir=".", filename="graph.html", version=this_version):
    """
    Arguments:
        networkx_graph (networkx.Graph): any instance of networkx.Graph
        title (str): The title of the plot (to be embedded in the html).
        scripts_mode (str): Choose from [`"CDN"`, `"directory"`, `"inline"`]:

            - `"CDN"` compiles a single HTML page with links to scripts hosted on a CDN,

            - `"directory"` compiles a directory with all scripts locally cached,

            - `"inline"` compiles a single HTML file with all scripts/styles inlined.

        data_mode (str): Choose from ["directory", "inline"]:

            - "directory" compiles a directory with all data locally cached,

            - "inline" compiles a single HTML file with all data inlined.

        output_dir (str): the directory in which to output the file
        filename (str): the filename of the output file
        version (str): the version of the javascripts to use.
            Leave the default to pin the version, or choose "latest" to get updates,
            or choose part of the version string to get minor updates.
    Returns:
        Path: The filepath which the html was outputted to.
    """

    output_dir = Path(output_dir)
    output_dir.mkdir(exist_ok=True, parents=True)

    # Scripts =======================

    scripts = third_party_scripts + [CDN_url(version)+"js/cola.min.js", CDN_url(version)+"js/graph.js"]

    scripts_block = _scripts_block(scripts, scripts_mode, output_dir)

    # Data    =======================

    graph_json = nx_json.node_link_data(networkx_graph)

    for node in graph_json['nodes']:
        for attr, val in node.items():
            if isinstance(val, numbers.Number):
                node[attr] = round(val, 2)
    for link in graph_json['links']:
        for attr, val in link.items():
            if isinstance(val, numbers.Number):
                link[attr] = round(val, 2)

    graph_json = f"var graph = {json.dumps(graph_json)};"

    data_block = _data_block(data_mode, [('graph', graph_json)], output_dir)

    html = templateEnv.get_template('graph.html.j2').render(title=title, scripts_block=scripts_block+'\n'+data_block, nodes=networkx_graph.nodes())

    (output_dir / filename).write_text(html)

    return (output_dir / filename).resolve()

Response: A function that generates the HTML for a single page of a graph.


Instruction:
Make a summary of the following Python 3 code
def db_connect(connection_string=None, **kwargs):
    if connection_string is None:
        connection_string = get_current_registry().settings[CONNECTION_STRING]
    db_conn = psycopg2.connect(connection_string, **kwargs)
    try:
        with db_conn:
            yield db_conn
    finally:
        db_conn.close()

Response: Function to supply a database connection object.


Instruction:
Here you have a function in Python 3, explain what it does
def with_db_cursor(func):

    @functools.wraps(func)
    def wrapped(*args, **kwargs):
        if 'cursor' in kwargs or func.func_code.co_argcount == len(args):
            return func(*args, **kwargs)
        with db_connect() as db_connection:
            with db_connection.cursor() as cursor:
                kwargs['cursor'] = cursor
                return func(*args, **kwargs)

    return wrapped

Response: Decorator that supplies a cursor to the function.


Instruction:
Given the following Python 3 function, write the documentation
def _role_type_to_db_type(type_):
    with db_connect() as db_conn:
        with db_conn.cursor() as cursor:
            cursor.execute("""\
WITH unnested_role_types AS (
  SELECT unnest(enum_range(NULL::role_types)) as role_type
  ORDER BY role_type ASC)
SELECT array_agg(role_type)::text[] FROM unnested_role_types""")
            db_types = cursor.fetchone()[0]
    return dict(zip(cnxepub.ATTRIBUTED_ROLE_KEYS, db_types))[type_]

Response:
Translates a role type to a database compatible
    value for role_types.


Instruction:
How would you implement a function in Python 3 that
gives a model s metadata iterate over the roles.

Response:
def _dissect_roles(metadata):
    """Given a model's ``metadata``, iterate over the roles.
    Return values are the role identifier and role type as a tuple.
    """
    for role_key in cnxepub.ATTRIBUTED_ROLE_KEYS:
        for user in metadata.get(role_key, []):
            if user['type'] != 'cnx-id':
                raise ValueError("Archive only accepts Connexions users.")
            uid = parse_user_uri(user['id'])
            yield uid, role_key
    raise StopIteration()


Instruction:
Can you implement a function in Python 3 that
updates or insert records for pending license acceptors.

Response:
def upsert_pending_licensors(cursor, document_id):
    """Update or insert records for pending license acceptors."""
    cursor.execute("""\
SELECT "uuid", "metadata"
FROM pending_documents
WHERE id = %s""", (document_id,))
    uuid_, metadata = cursor.fetchone()
    acceptors = set([uid for uid, type_ in _dissect_roles(metadata)])

    # Acquire a list of existing acceptors.
    cursor.execute("""\
SELECT "user_id", "accepted"
FROM license_acceptances
WHERE uuid = %s""", (uuid_,))
    existing_acceptors_mapping = dict(cursor.fetchall())

    # Who's not in the existing list?
    existing_acceptors = set(existing_acceptors_mapping.keys())
    new_acceptors = acceptors.difference(existing_acceptors)

    # Insert the new licensor acceptors.
    for acceptor in new_acceptors:
        cursor.execute("""\
INSERT INTO license_acceptances
  ("uuid", "user_id", "accepted")
VALUES (%s, %s, NULL)""", (uuid_, acceptor,))

    # Has everyone already accepted?
    cursor.execute("""\
SELECT user_id
FROM license_acceptances
WHERE
  uuid = %s
  AND
  (accepted is UNKNOWN OR accepted is FALSE)""", (uuid_,))
    defectors = set(cursor.fetchall())

    if not defectors:
        # Update the pending document license acceptance state.
        cursor.execute("""\
update pending_documents set license_accepted = 't'
where id = %s""", (document_id,))


Instruction:
Create a Python 3 function to
update or insert records for pending document role acceptance.

Response:
def upsert_pending_roles(cursor, document_id):
    """Update or insert records for pending document role acceptance."""
    cursor.execute("""\
SELECT "uuid", "metadata"
FROM pending_documents
WHERE id = %s""", (document_id,))
    uuid_, metadata = cursor.fetchone()

    acceptors = set([(uid, _role_type_to_db_type(type_),)
                     for uid, type_ in _dissect_roles(metadata)])

    # Upsert the user info.
    upsert_users(cursor, [x[0] for x in acceptors])

    # Acquire a list of existing acceptors.
    cursor.execute("""\
SELECT user_id, role_type
FROM role_acceptances
WHERE uuid = %s""", (uuid_,))
    existing_roles = set([(r, t,) for r, t in cursor.fetchall()])

    # Who's not in the existing list?
    existing_acceptors = existing_roles
    new_acceptors = acceptors.difference(existing_acceptors)

    # Insert the new role acceptors.
    for acceptor, type_ in new_acceptors:
        cursor.execute("""\
INSERT INTO role_acceptances
  ("uuid", "user_id", "role_type", "accepted")
        VALUES (%s, %s, %s, DEFAULT)""", (uuid_, acceptor, type_))

    # Has everyone already accepted?
    cursor.execute("""\
SELECT user_id
FROM role_acceptances
WHERE
  uuid = %s
  AND
  (accepted is UNKNOWN OR accepted is FALSE)""", (uuid_,))
    defectors = set(cursor.fetchall())

    if not defectors:
        # Update the pending document license acceptance state.
        cursor.execute("""\
update pending_documents set roles_accepted = 't'
where id = %s""", (document_id,))


Instruction:
Make a summary of the following Python 3 code
def obtain_licenses():
    with db_connect() as db_conn:
        with db_conn.cursor() as cursor:
            cursor.execute("""\
SELECT combined_row.url, row_to_json(combined_row) FROM (
  SELECT "code", "version", "name", "url", "is_valid_for_publication"
  FROM licenses) AS combined_row""")
            licenses = {r[0]: r[1] for r in cursor.fetchall()}
    return licenses

Response: Obtain the licenses in a dictionary form keyed by url.


Instruction:
Can you generate the documentation for the following Python 3 function
def _validate_license(model):
    license_mapping = obtain_licenses()
    try:
        license_url = model.metadata['license_url']
    except KeyError:
        raise exceptions.MissingRequiredMetadata('license_url')
    try:
        license = license_mapping[license_url]
    except KeyError:
        raise exceptions.InvalidLicense(license_url)
    if not license['is_valid_for_publication']:
        raise exceptions.InvalidLicense(license_url)

Response: Given the model check the license is one valid for publication.


Instruction:
How would you implement a function in Python 3 that
validates that all the metadata roles in the given model have valid information in them.

Response:
def _validate_roles(model):
    """Given the model, check that all the metadata role values
    have valid information in them and any required metadata fields
    contain values.
    """
    required_roles = (ATTRIBUTED_ROLE_KEYS[0], ATTRIBUTED_ROLE_KEYS[4],)
    for role_key in ATTRIBUTED_ROLE_KEYS:
        try:
            roles = model.metadata[role_key]
        except KeyError:
            if role_key in required_roles:
                raise exceptions.MissingRequiredMetadata(role_key)
        else:
            if role_key in required_roles and len(roles) == 0:
                raise exceptions.MissingRequiredMetadata(role_key)
        for role in roles:
            if role.get('type') != 'cnx-id':
                raise exceptions.InvalidRole(role_key, role)


Instruction:
Write a Python 3 script for
validating that the derived_from_uri is correctly set.

Response:
def _validate_derived_from(cursor, model):
    """Given a database cursor and model, check the derived-from
    value accurately points to content in the archive.
    The value can be nothing or must point to existing content.
    """
    derived_from_uri = model.metadata.get('derived_from_uri')
    if derived_from_uri is None:
        return  # bail out early

    # Can we parse the value?
    try:
        ident_hash = parse_archive_uri(derived_from_uri)
        uuid_, version = split_ident_hash(ident_hash, split_version=True)
    except (ValueError, IdentHashSyntaxError, IdentHashShortId) as exc:
        raise exceptions.InvalidMetadata('derived_from_uri', derived_from_uri,
                                         original_exception=exc)
    # Is the ident-hash a valid pointer?
    args = [uuid_]
    table = 'modules'
    version_condition = ''
    if version != (None, None,):
        args.extend(version)
        table = 'modules'
        version_condition = " AND major_version = %s" \
                            " AND minor_version {} %s" \
                            .format(version[1] is None and 'is' or '=')
    cursor.execute("""SELECT 't' FROM {} WHERE uuid::text = %s{}"""
                   .format(table, version_condition), args)
    try:
        _exists = cursor.fetchone()[0]  # noqa
    except TypeError:  # None type
        raise exceptions.InvalidMetadata('derived_from_uri', derived_from_uri)

    # Assign the derived_from value so that we don't have to split it again.
    model.metadata['derived_from'] = ident_hash


Instruction:
How would you code a function in Python 3 to
check the subjects against the subject vocabulary.

Response:
def _validate_subjects(cursor, model):
    """Give a database cursor and model, check the subjects against
    the subject vocabulary.
    """
    subject_vocab = [term[0] for term in acquire_subject_vocabulary(cursor)]
    subjects = model.metadata.get('subjects', [])
    invalid_subjects = [s for s in subjects if s not in subject_vocab]
    if invalid_subjects:
        raise exceptions.InvalidMetadata('subjects', invalid_subjects)


Instruction:
Create a Python 3 function for
validating the model using a series of checks on bits of the data.

Response:
def validate_model(cursor, model):
    """Validates the model using a series of checks on bits of the data."""
    # Check the license is one valid for publication.
    _validate_license(model)
    _validate_roles(model)

    # Other required metadata includes: title, summary
    required_metadata = ('title', 'summary',)
    for metadata_key in required_metadata:
        if model.metadata.get(metadata_key) in [None, '', []]:
            raise exceptions.MissingRequiredMetadata(metadata_key)

    # Ensure that derived-from values are either None
    # or point at a live record in the archive.
    _validate_derived_from(cursor, model)

    # FIXME Valid language code?

    # Are the given 'subjects'
    _validate_subjects(cursor, model)


Instruction:
How would you implement a function in Python 3 that
checks if the given publisher of this publication is allowed to publish the content given by uuid.

Response:
def is_publication_permissible(cursor, publication_id, uuid_):
    """Check the given publisher of this publication given
    by ``publication_id`` is allowed to publish the content given
    by ``uuid``.
    """
    # Check the publishing user has permission to publish
    cursor.execute("""\
SELECT 't'::boolean
FROM
  pending_documents AS pd
  NATURAL JOIN document_acl AS acl
  JOIN publications AS p ON (pd.publication_id = p.id)
WHERE
  p.id = %s
  AND
  pd.uuid = %s
  AND
  p.publisher = acl.user_id
  AND
  acl.permission = 'publish'""", (publication_id, uuid_,))
    try:
        is_allowed = cursor.fetchone()[0]
    except TypeError:
        is_allowed = False
    return is_allowed


Instruction:
Explain what the following Python 3 code does
def add_pending_model(cursor, publication_id, model):
    # FIXME Too much happening here...
    assert isinstance(model, (cnxepub.Document, cnxepub.Binder,)), type(model)
    uri = model.get_uri('cnx-archive')

    if uri is not None:
        ident_hash = parse_archive_uri(uri)
        id, version = split_ident_hash(ident_hash, split_version=True)
        cursor.execute("""\
SELECT major_version + 1 as next_version
FROM latest_modules
WHERE uuid = %s
UNION ALL
SELECT 1 as next_version
ORDER BY next_version DESC
LIMIT 1
""", (id,))
        next_major_version = cursor.fetchone()[0]
        if isinstance(model, cnxepub.Document):
            version = (next_major_version, None,)
        else:  # ...assume it's a binder.
            version = (next_major_version, 1,)
    else:
        cursor.execute("""\
WITH
control_insert AS (
  INSERT INTO document_controls (uuid) VALUES (DEFAULT) RETURNING uuid),
acl_insert AS (
  INSERT INTO document_acl (uuid, user_id, permission)
  VALUES ((SELECT uuid FROM control_insert),
          (SELECT publisher FROM publications WHERE id = %s),
          'publish'::permission_type))
SELECT uuid FROM control_insert""", (publication_id,))
        id = cursor.fetchone()[0]
        if isinstance(model, cnxepub.Document):
            version = (1, None,)
        else:  # ...assume it's a binder.
            version = (1, 1,)

    type_ = _get_type_name(model)
    model.id = str(id)
    model.metadata['version'] = '.'.join([str(v) for v in version if v])
    args = [publication_id, id, version[0], version[1], type_,
            json.dumps(model.metadata)]
    cursor.execute("""\
INSERT INTO "pending_documents"
  ("publication_id", "uuid", "major_version", "minor_version", "type",
    "license_accepted", "roles_accepted", "metadata")
VALUES (%s, %s, %s, %s, %s, 'f', 'f', %s)
RETURNING "id", "uuid", module_version("major_version", "minor_version")
""", args)
    pending_id, uuid_, version = cursor.fetchone()
    pending_ident_hash = join_ident_hash(uuid_, version)

    # Assign the new ident-hash to the document for later use.
    request = get_current_request()
    path = request.route_path('get-content', ident_hash=pending_ident_hash)
    model.set_uri('cnx-archive', path)

    # Check if the publication is allowed for the publishing user.
    if not is_publication_permissible(cursor, publication_id, id):
        # Set the failure but continue the operation of inserting
        # the pending document.
        exc = exceptions.NotAllowed(id)
        exc.publication_id = publication_id
        exc.pending_document_id = pending_id
        exc.pending_ident_hash = pending_ident_hash
        set_publication_failure(cursor, exc)

    try:
        validate_model(cursor, model)
    except exceptions.PublicationException as exc:
        exc_info = sys.exc_info()
        exc.publication_id = publication_id
        exc.pending_document_id = pending_id
        exc.pending_ident_hash = pending_ident_hash
        try:
            set_publication_failure(cursor, exc)
        except BaseException:
            import traceback
            print("Critical data error. Immediate attention is "
                  "required. On publication at '{}'."
                  .format(publication_id),
                  file=sys.stderr)
            # Print the critical exception.
            traceback.print_exc()
            # Raise the previous exception, so we know the original cause.
            raise exc_info[0], exc_info[1], exc_info[2]
    else:
        upsert_pending_licensors(cursor, pending_id)
        upsert_pending_roles(cursor, pending_id)
        notify_users(cursor, pending_id)
    return pending_ident_hash

Response:
Adds a pending model that is awaiting publication
    to the database.