Instruction:
Here you have a function in Python 3, explain what it does
def nick(self):
        if '!' in self:
            return self.split('!', 1)[0]
        if not self.is_channel and not self.is_server:
            return self

Response:
return nick name:

        .. code-block:: py

            >>> print(IrcString('foo').nick)
            foo
            >>> print(IrcString('foo!user@host').nick)
            foo
            >>> IrcString('#foo').nick is None
            True
            >>> IrcString('irc.freenode.net').nick is None
            True


Instruction:
Write a Python 3 function for
returning a dict converted from this string interpreted as a tag - string .. code - block :: py

Response:
def tagdict(self):
        """return a dict converted from this string interpreted as a tag-string

        .. code-block:: py

            >>> from pprint import pprint
            >>> dict_ = IrcString('aaa=bbb;ccc;example.com/ddd=eee').tagdict
            >>> pprint({str(k): str(v) for k, v in dict_.items()})
            {'aaa': 'bbb', 'ccc': 'None', 'example.com/ddd': 'eee'}
        """
        tagdict = getattr(self, '_tagdict', None)
        if tagdict is None:
            try:
                self._tagdict = tags.decode(self)
            except ValueError:
                self._tagdict = {}
        return self._tagdict


Instruction:
Write a Python 3 script to
add a handler using bot and log to targets

Response:
def set_irc_targets(self, bot, *targets):
        """Add a irc Handler using bot and log to targets (can be nicks or
        channels:

        ..
            >>> bot = None

        .. code-block:: python

            >>> log = logging.getLogger('irc.mymodule')
            >>> log.set_irc_targets(bot, '#chan', 'admin')
        """
        # get formatter initialized by config (usualy on a NullHandler)
        ll = logging.getLogger('irc')
        formatter = ll.handlers[0].formatter
        # add a handler for the sub logger
        handler = Handler(bot, *targets)
        handler.setFormatter(formatter)
        self.addHandler(handler)


Instruction:
How would you implement a function in Python 3 that
sends a line to the server. replace CR by spaces

Response:
def send_line(self, data, nowait=False):
        """send a line to the server. replace CR by spaces"""
        data = data.replace('\n', ' ').replace('\r', ' ')
        f = asyncio.Future(loop=self.loop)
        if self.queue is not None and nowait is False:
            self.queue.put_nowait((f, data))
        else:
            self.send(data.replace('\n', ' ').replace('\r', ' '))
            f.set_result(True)
        return f


Instruction:
Create a Python 3 function for
sending a privmsg to target

Response:
def privmsg(self, target, message, nowait=False):
        """send a privmsg to target"""
        if message:
            messages = utils.split_message(message, self.config.max_length)
            if isinstance(target, DCCChat):
                for message in messages:
                    target.send_line(message)
            elif target:
                f = None
                for message in messages:
                    f = self.send_line('PRIVMSG %s :%s' % (target, message),
                                       nowait=nowait)
                return f


Instruction:
Create a Python 3 function for
sending a ctcp to target

Response:
def ctcp(self, target, message, nowait=False):
        """send a ctcp to target"""
        if target and message:
            messages = utils.split_message(message, self.config.max_length)
            f = None
            for message in messages:
                f = self.send_line('PRIVMSG %s :\x01%s\x01' % (target,
                                                               message),
                                   nowait=nowait)
            return f


Instruction:
Can you tell what is the following Python 3 function doing
def mode(self, target, *data):
        self.send_line('MODE %s %s' % (target, ' '.join(data)), nowait=True)

Response: set user or channel mode


Instruction:
How would you explain what the following Python 3 function does
def kick(self, channel, target, reason=None):
        if reason:
            target += ' :' + reason
        self.send_line('KICK %s %s' % (channel, target), nowait=True)

Response: kick target from channel


Instruction:
Write a Python 3 script to
change or request the topic of a channel

Response:
def topic(self, channel, topic=None):
        """change or request the topic of a channel"""
        if topic:
            channel += ' :' + topic
        self.send_line('TOPIC %s' % channel)


Instruction:
Can you write a function in Python 3 where it
marks ourself as away

Response:
def away(self, message=None):
        """mark ourself as away"""
        cmd = 'AWAY'
        if message:
            cmd += ' :' + message
        self.send_line(cmd)


Instruction:
Write a Python 3 function that can
return bot s ip as an ip_address object

Response:
def ip(self):
        """return bot's ip as an ``ip_address`` object"""
        if not self._ip:
            if 'ip' in self.config:
                ip = self.config['ip']
            else:
                ip = self.protocol.transport.get_extra_info('sockname')[0]
            ip = ip_address(ip)
            if ip.version == 4:
                self._ip = ip
            else:  # pragma: no cover
                response = urlopen('http://ipv4.icanhazip.com/')
                ip = response.read().strip().decode()
                ip = ip_address(ip)
                self._ip = ip
        return self._ip


Instruction:
Make a summary of the following Python 3 code
def dcc(self):
        if self._dcc is None:
            self._dcc = DCCManager(self)
        return self._dcc

Response: return the : class : ~irc3. dcc. DCCManager object


Instruction:
Can you implement a function in Python 3 that
opens a DCC CHAT whith mask.

Response:
def dcc_chat(self, mask, host=None, port=None):
        """Open a DCC CHAT whith mask. If host/port are specified then connect
        to a server. Else create a server"""
        return self.dcc.create(
            'chat', mask, host=host, port=port).ready


Instruction:
How would you explain what the following Python 3 function does
def dcc_send(self, mask, filepath):
        return self.dcc.create('send', mask, filepath=filepath).ready

Response: Send a file to mask. filepath must be an absolute path to the existing file.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def dcc_accept(self, mask, filepath, port, pos):
        return self.dcc.resume(mask, filepath, port, pos)

Response: accept a DCC RESUME for an axisting DCC SEND


Instruction:
Can you write a function in Python 3 where it
encodes a dictionary of tags to fit into an IRC - message.

Response:
def encode(tags):
    '''Encodes a dictionary of tags to fit into an IRC-message.
    See IRC Message Tags: http://ircv3.net/specs/core/message-tags-3.2.html

    >>> from collections import OrderedDict
    >>> encode({'key': 'value'})
    'key=value'

    >>> d = {'aaa': 'bbb', 'ccc': None, 'example.com/ddd': 'eee'}
    >>> d_ordered = OrderedDict(sorted(d.items(), key=lambda t: t[0]))
    >>> encode(d_ordered)
    'aaa=bbb;ccc;example.com/ddd=eee'

    >>> d = {'key': 'value;with special\\\\characters', 'key2': 'with=equals'}
    >>> d_ordered = OrderedDict(sorted(d.items(), key=lambda t: t[0]))
    >>> print(encode(d_ordered))
    key=value\\:with\\sspecial\\\characters;key2=with=equals

    >>> print(encode({'key': r'\\something'}))
    key=\\\\something

    '''
    tagstrings = []
    for key, value in tags.items():
        if not _valid_key.match(key):
            raise ValueError("dictionary key is invalid as tag key: " + key)
        # if no value, just append the key
        if value:
            tagstrings.append(key + "=" + _escape(value))
        else:
            tagstrings.append(key)
    return ";".join(tagstrings)


Instruction:
Can you generate the documentation for the following Python 3 function
def decode(tagstring):
    '''Decodes a tag-string from an IRC-message into a python dictionary.
    See IRC Message Tags: http://ircv3.net/specs/core/message-tags-3.2.html

    >>> from pprint import pprint
    >>> pprint(decode('key=value'))
    {'key': 'value'}

    >>> pprint(decode('aaa=bbb;ccc;example.com/ddd=eee'))
    {'aaa': 'bbb', 'ccc': None, 'example.com/ddd': 'eee'}

    >>> s = r'key=value\\:with\\sspecial\\\\characters;key2=with=equals'
    >>> pprint(decode(s))
    {'key': 'value;with special\\\\characters', 'key2': 'with=equals'}
    >>> print(decode(s)['key'])
    value;with special\\characters

    >>> print(decode(r'key=\\\\something')['key'])
    \\something

    '''
    if not tagstring:
        # None/empty = no tags
        return {}

    tags = {}

    for tag in tagstring.split(";"):
        # value is either everything after "=", or None
        key, value = (tag.split("=", 1) + [None])[:2]
        if not _valid_key.match(key):
            raise ValueError("invalid tag key: " + key)
        if value:
            if not _valid_escaped_value.match(value):
                raise ValueError("invalid escaped tag value: " + value)
            value = _unescape(value)
        tags[key] = value

    return tags

Response: Decodes a tag - string from an IRC - message into a python dictionary.


Instruction:
Write a Python 3 function that can
calculate the challenge auth hash for the user and password.

Response:
def challenge_auth(username, password, challenge, lower, digest='sha256'):
    """Calculates quakenet's challenge auth hash

    .. code-block:: python

        >>> challenge_auth("mooking", "0000000000",
        ...     "12345678901234567890123456789012", str.lower, "md5")
        '2ed1a1f1d2cd5487d2e18f27213286b9'
    """
    def hdig(x):
        return fdigest(x).hexdigest()

    fdigest = get_digest(digest)
    luser = lower(username)
    tpass = password[:10].encode("ascii")
    hvalue = hdig("{0}:{1}".format(luser, hdig(tpass)).encode("ascii"))
    bhvalue = hvalue.encode("ascii")
    bchallenge = challenge.encode("ascii")
    return hmac.HMAC(bhvalue, bchallenge, digestmod=fdigest).hexdigest()


Instruction:
Can you generate the documentation for the following Python 3 function
def filter_travis(self, entry):
        fstate = entry.filename + '.state'
        if os.path.isfile(fstate):
            with open(fstate) as fd:
                state = fd.read().strip()
        else:
            state = None
        if 'failed' in entry.summary:
            nstate = 'failed'
        else:
            nstate = 'success'
        with open(fstate, 'w') as fd:
            fd.write(nstate)
        if state != nstate:
            build = entry.title.split('#')[1]
            entry['title'] = 'Build #{0} {1}'.format(build, nstate)
            return True

Response: Only show the latest entry iif this entry is in a new state


Instruction:
Write a Python 3 function that can
filter out only usefull packages

Response:
def filter_pypi(self, entry):
        """Show only usefull packages"""
        for package in self.packages:
            if entry.title.lower().startswith(package):
                return entry


Instruction:
Write a Python 3 script to
take results list of all events and put them in a dict

Response:
def process_results(self, results=None, **value):
        """take results list of all events and put them in a dict"""
        channels = []
        for res in results:
            channels.extend(res.pop('channels', '').split())
            value.update(res)
        value['channels'] = channels
        value['success'] = value.get('retcode') == '318'
        return value


Instruction:
Can you create a Python 3 function that
takes results list of all events and return first dict

Response:
def process_results(self, results=None, **value):
        """take results list of all events and return first dict"""
        for res in results:
            if 'mask' in res:
                res['mask'] = utils.IrcString(res['mask'])
            value['success'] = res.pop('retcode', None) != '486'
            value.update(res)
        return value


Instruction:
Can you generate the documentation for the following Python 3 function
def ping(bot, mask, target, args):
    bot.send('NOTICE %(nick)s :PONG %(nick)s!' % dict(nick=mask.nick))

Response: ping is a hack to send a NOTICE message to the bot.


Instruction:
Can you implement a function in Python 3 that
sends a quote to the server %%quote <args >...

Response:
def quote(bot, mask, target, args):
    """send quote to the server

        %%quote <args>...
    """
    msg = ' '.join(args['<args>'])
    bot.log.info('quote> %r', msg)
    bot.send(msg)


Instruction:
Explain what the following Python 3 code does
def connected(self, **kwargs):
        self.bot.log.info('Server config: %r', self.bot.server_config)

        # recompile when I'm sure of my nickname
        self.bot.config['nick'] = kwargs['me']
        self.bot.recompile()

        # Let all plugins know that server can handle commands
        self.bot.notify('server_ready')

        # detach useless events
        self.bot.detach_events(*self.before_connect_events)

Response: triger the server_ready event


Instruction:
Given the following Python 3 function, write the documentation
def recompile(self, nick=None, new_nick=None, **kw):
        if self.bot.nick == nick.nick:
            self.bot.config['nick'] = new_nick
            self.bot.recompile()

Response: recompile regexp on new nick


Instruction:
Can you tell what is the following Python 3 function doing
def badnick(self, me=None, nick=None, **kw):
        if me == '*':
            self.bot.set_nick(self.bot.nick + '_')
        self.bot.log.debug('Trying to regain nickname in 30s...')
        self.nick_handle = self.bot.loop.call_later(
            30, self.bot.set_nick, self.bot.original_nick)

Response: Use alt nick on nick error


Instruction:
Create a Python 3 function to
parse a feed using feedparser

Response:
def parse(feedparser, args):
    """parse a feed using feedparser"""
    entries = []
    args = irc3.utils.Config(args)
    max_date = datetime.datetime.now() - datetime.timedelta(days=2)

    for filename in args['filenames']:
        try:
            with open(filename + '.updated') as fd:
                updated = fd.read().strip()
        except (OSError, IOError):
            updated = '0'

        feed = feedparser.parse(filename)
        for e in feed.entries:
            if e.updated <= updated:
                # skip already sent entries
                continue
            try:
                updated_parsed = e.updated_parsed
            except AttributeError:
                continue
            if datetime.datetime(*updated_parsed[:7]) < max_date:
                # skip entries older than 2 days
                continue
            e['filename'] = filename
            e['feed'] = args
            entries.append((e.updated, e))
        if entries:
            entries = sorted(entries, key=itemgetter(0))
            with open(filename + '.updated', 'w') as fd:
                fd.write(str(entries[-1][0]))
    return entries


Instruction:
How would you code a function in Python 3 to
attach one or more events to the bot instance

Response:
def attach_events(self, *events, **kwargs):
        """Attach one or more events to the bot instance"""
        reg = self.registry
        insert = 'insert' in kwargs
        for e in events:
            cregexp = e.compile(self.config)
            regexp = getattr(e.regexp, 're', e.regexp)
            if regexp not in reg.events[e.iotype]:
                if insert:
                    reg.events_re[e.iotype].insert(0, (regexp, cregexp))
                else:
                    reg.events_re[e.iotype].append((regexp, cregexp))
            if insert:
                reg.events[e.iotype][regexp].insert(0, e)
            else:
                reg.events[e.iotype][regexp].append(e)


Instruction:
Implement a Python 3 function for
detaching one or more events from the bot instance

Response:
def detach_events(self, *events):
        """Detach one or more events from the bot instance"""
        reg = self.registry
        delete = defaultdict(list)

        # remove from self.events
        all_events = reg.events
        for e in events:
            regexp = getattr(e.regexp, 're', e.regexp)
            iotype = e.iotype
            if e in all_events[iotype].get(regexp, []):
                all_events[iotype][regexp].remove(e)
                if not all_events[iotype][regexp]:
                    del all_events[iotype][regexp]
                    # need to delete from self.events_re
                    delete[iotype].append(regexp)

        # delete from events_re
        for iotype, regexps in delete.items():
            reg.events_re[iotype] = [r for r in reg.events_re[iotype]
                                     if r[0] not in regexps]


Instruction:
Can you tell what is the following Python 3 function doing
def reload(self, *modules):
        self.notify('before_reload')

        if 'configfiles' in self.config:
            # reload configfiles
            self.log.info('Reloading configuration...')
            cfg = utils.parse_config(
                self.server and 'server' or 'bot', *self.config['configfiles'])
            self.config.update(cfg)

        self.log.info('Reloading python code...')
        if not modules:
            modules = self.registry.includes
        scanned = list(reversed(self.registry.scanned))

        # reset includes and events
        self.registry.reset()

        to_scan = []
        for module_name, categories in scanned:
            if module_name in modules:
                module = utils.maybedotted(module_name)
                reload_module(module)
            to_scan.append((module_name, categories))

        # rescan all modules
        for module_name, categories in to_scan:
            self.include(module_name, venusian_categories=categories)

        self.registry.reloading = {}

        self.notify('after_reload')

Response: Reload one or more modules


Instruction:
Can you tell what is the following Python 3 function doing
def add_signal_handlers(self):
        try:
            self.loop.add_signal_handler(signal.SIGHUP, self.SIGHUP)
        except (RuntimeError, AttributeError):  # pragma: no cover
            # windows
            pass
        try:
            self.loop.add_signal_handler(signal.SIGINT, self.SIGINT)
        except (RuntimeError, NotImplementedError):  # pragma: no cover
            # annaconda
            pass

Response: Register handlers for UNIX signals ( SIGGHUP and SIGINT.


Instruction:
Create a Python 3 function for
returning an instance configured with the cfg dict

Response:
def from_config(cls, cfg, **kwargs):
        """return an instance configured with the ``cfg`` dict"""
        cfg = dict(cfg, **kwargs)
        pythonpath = cfg.get('pythonpath', [])
        if 'here' in cfg:
            pythonpath.append(cfg['here'])
        for path in pythonpath:
            sys.path.append(os.path.expanduser(path))
        prog = cls.server and 'irc3d' or 'irc3'
        if cfg.get('debug'):
            cls.venusian_categories.append(prog + '.debug')
        if cfg.get('interactive'):  # pragma: no cover
            import irc3.testing
            context = getattr(irc3.testing, cls.__name__)(**cfg)
        else:
            context = cls(**cfg)
        if cfg.get('raw'):
            context.include('irc3.plugins.log',
                            venusian_categories=[prog + '.debug'])
        return context


Instruction:
Make a summary of the following Python 3 code
def async_run(self, keyword, *args, **kwargs):
        ''' Executes the provided Robot Framework keyword in a separate thread and immediately returns a handle to be used with async_get '''
        handle = self._last_thread_handle
        thread = self._threaded(keyword, *args, **kwargs)
        thread.start()
        self._thread_pool[handle] = thread
        self._last_thread_handle += 1
        return handle

Response: Executes the provided Robot Framework keyword in a separate thread and immediately returns a handle to be used with async_get


Instruction:
Implement a Python 3 function for
blocking until the thread created by async_run returns

Response:
def async_get(self, handle):
        ''' Blocks until the thread created by async_run returns '''
        assert handle in self._thread_pool, 'Invalid async call handle'
        result = self._thread_pool[handle].result_queue.get()
        del self._thread_pool[handle]
        return result


Instruction:
Can you write a function in Python 3 where it
gets the handler associated with the given keyword

Response:
def _get_handler_from_keyword(self, keyword):
        ''' Gets the Robot Framework handler associated with the given keyword '''
        if EXECUTION_CONTEXTS.current is None:
            raise RobotNotRunningError('Cannot access execution context')
        return EXECUTION_CONTEXTS.current.get_handler(keyword)


Instruction:
How would you implement a function in Python 3 that
sets the _PMMail__custom_headers attribute.

Response:
def _set_custom_headers(self, value):
        '''
        A special set function to ensure
        we're setting with a dictionary
        '''
        if value is None:
            setattr(self, '_PMMail__custom_headers', {})
        elif isinstance(value, dict):
            setattr(self, '_PMMail__custom_headers', value)
        else:
            raise TypeError('Custom headers must be a dictionary of key-value pairs')


Instruction:
Make a summary of the following Python 3 code
def _set_metadata(self, value):
        '''
        A special set function to ensure
        we're setting with a dictionary
        '''
        if value is None:
            setattr(self, '_PMMail__metadata', {})
        elif isinstance(value, dict):
            for k, v in value.items():
                if (not isinstance(k, str) and not isinstance(k, int)) \
                    or (not isinstance(v, str) and not isinstance(v, int)):
                    raise TypeError('Metadata keys and values can only be strings or integers')
            setattr(self, '_PMMail__metadata', value)
        else:
            raise TypeError('Metadata must be a dictionary of key-value pairs')

Response: Set the metadata of the object.


Instruction:
Can you implement a function in Python 3 that
sets the _PMMail__attachments attribute.

Response:
def _set_attachments(self, value):
        '''
        A special set function to ensure
        we're setting with a list
        '''
        if value is None:
            setattr(self, '_PMMail__attachments', [])
        elif isinstance(value, list):
            setattr(self, '_PMMail__attachments', value)
        else:
            raise TypeError('Attachments must be a list')


Instruction:
Create a Python 3 function for
checking that all values are of the appropriate type and are not missing.

Response:
def _check_values(self):
        '''
        Make sure all values are of the appropriate
        type and are not missing.
        '''
        if not self.__api_key:
            raise PMMailMissingValueException('Cannot send an e-mail without a Postmark API Key')
        elif not self.__sender:
            raise PMMailMissingValueException('Cannot send an e-mail without a sender (.sender field)')
        elif not self.__to:
            raise PMMailMissingValueException('Cannot send an e-mail without at least one recipient (.to field)')
        elif (self.__template_id or self.__template_model) and not all([self.__template_id, self.__template_model]):
            raise PMMailMissingValueException(
                'Cannot send a template e-mail without a both template_id and template_model set')
        elif not any([self.__template_id, self.__template_model, self.__subject]):
            raise PMMailMissingValueException('Cannot send an e-mail without a subject')
        elif not self.__html_body and not self.__text_body and not self.__template_id:
            raise PMMailMissingValueException('Cannot send an e-mail without either an HTML or text version of your e-mail body')
        if self.__track_opens and not self.__html_body:
            print('WARNING: .track_opens set to True with no .html_body set. Tracking opens will not work; message will still send.')


Instruction:
Make a summary of the following Python 3 code
def send(self, test=None):
        '''
        Send the email through the Postmark system.
        Pass test=True to just print out the resulting
        JSON message being sent to Postmark
        '''
        self._check_values()

        # Set up message dictionary
        json_message = self.to_json_message()

        # if (self.__html_body and not self.__text_body) and self.__multipart:
        #     # TODO: Set up regex to strip html
        #     pass

        # If test is not specified, attempt to read the Django setting
        if test is None:
            try:
                from django.conf import settings as django_settings
                test = getattr(django_settings, "POSTMARK_TEST_MODE", None)
            except ImportError:
                pass

        # If this is a test, just print the message
        if test:
            print('JSON message is:\n%s' % json.dumps(json_message, cls=PMJSONEncoder))
            return

        if self.__template_id:
            endpoint_url = __POSTMARK_URL__ + 'email/withTemplate/'
        else:
            endpoint_url = __POSTMARK_URL__ + 'email'

        # Set up the url Request
        req = Request(
            endpoint_url,
            json.dumps(json_message, cls=PMJSONEncoder).encode('utf8'),
            {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'X-Postmark-Server-Token': self.__api_key,
                'User-agent': self.__user_agent
            }
        )

        # Attempt send
        try:
            # print 'sending request to postmark: %s' % json_message
            result = urlopen(req)
            jsontxt = result.read().decode('utf8')
            result.close()
            if result.code == 200:
                self.message_id = json.loads(jsontxt).get('MessageID', None)
                return True
            else:
                raise PMMailSendException('Return code %d: %s' % (result.code, result.msg))
        except HTTPError as err:
            if err.code == 401:
                raise PMMailUnauthorizedException('Sending Unauthorized - incorrect API key.', err)
            elif err.code == 422:
                try:
                    jsontxt = err.read().decode('utf8')
                    jsonobj = json.loads(jsontxt)
                    desc = jsonobj['Message']
                    error_code = jsonobj['ErrorCode']
                except KeyError:
                    raise PMMailUnprocessableEntityException('Unprocessable Entity: Description not given')

                if error_code == 406:
                    raise PMMailInactiveRecipientException('You tried to send email to a recipient that has been marked as inactive.')

                raise PMMailUnprocessableEntityException('Unprocessable Entity: %s' % desc)
            elif err.code == 500:
                raise PMMailServerErrorException('Internal server error at Postmark. Admins have been alerted.', err)
        except URLError as err:
            if hasattr(err, 'reason'):
                raise PMMailURLException('URLError: Failed to reach the server: %s (See "inner_exception" for details)' % err.reason, err)
            elif hasattr(err, 'code'):
                raise PMMailURLException('URLError: %d: The server couldn\'t fufill the request. (See "inner_exception" for details)' % err.code, err)
            else:
                raise PMMailURLException('URLError: The server couldn\'t fufill the request. (See "inner_exception" for details)', err)

Response:
Send the email through the Postmark system. Pass test = True to just print out the resulting
            JSON message being sent to Postmark.


Instruction:
Write a Python 3 script for
removing a message from the batch.

Response:
def remove_message(self, message):
        '''
        Remove a message from the batch
        '''
        if message in self.__messages:
            self.__messages.remove(message)


Instruction:
How would you implement a function in Python 3 that
returns a summary of inactive emails and bounces by type.

Response:
def delivery_stats(self):
        '''
        Returns a summary of inactive emails and bounces by type.
        '''
        self._check_values()

        req = Request(
            __POSTMARK_URL__ + 'deliverystats',
            None,
            {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'X-Postmark-Server-Token': self.__api_key,
                'User-agent': self.__user_agent
            }
        )

        # Attempt send
        try:
            # print 'sending request to postmark:'
            result = urlopen(req)
            with closing(result):
                if result.code == 200:
                    return json.loads(result.read())
                else:
                    raise PMMailSendException('Return code %d: %s' % (result.code, result.msg))

        except HTTPError as err:
            return err


Instruction:
Can you implement a function in Python 3 that
fetches a portion of bounces according to the input criteria.

Response:
def get_all(self, inactive='', email_filter='', tag='', count=25, offset=0):
        '''
        Fetches a portion of bounces according to the specified input criteria. The count and offset
        parameters are mandatory. You should never retrieve all bounces as that could be excessively
        slow for your application. To know how many bounces you have, you need to request a portion
        first, usually the first page, and the service will return the count in the TotalCount property
        of the response.
        '''

        self._check_values()

        params = '?inactive=' + inactive + '&emailFilter=' + email_filter +'&tag=' + tag
        params += '&count=' + str(count) + '&offset=' + str(offset)

        req = Request(
            __POSTMARK_URL__ + 'bounces' + params,
            None,
            {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'X-Postmark-Server-Token': self.__api_key,
                'User-agent': self.__user_agent
            }
        )

        # Attempt send
        try:
            # print 'sending request to postmark:'
            result = urlopen(req)
            with closing(result):
                if result.code == 200:
                    return json.loads(result.read())
                else:
                    raise PMMailSendException('Return code %d: %s' % (result.code, result.msg))

        except HTTPError as err:
            return err


Instruction:
Can you implement a function in Python 3 that
activates a deactivated bounce.

Response:
def activate(self, bounce_id):
        '''
        Activates a deactivated bounce.
        '''
        self._check_values()
        req_url = '/bounces/' + str(bounce_id) + '/activate'
        # print req_url
        h1 = HTTPConnection('api.postmarkapp.com')
        dta = urlencode({"data": "blank"}).encode('utf8')
        req = h1.request(
            'PUT',
            req_url,
            dta,
            {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'X-Postmark-Server-Token': self.__api_key,
                'User-agent': self.__user_agent
            }
        )
        r = h1.getresponse()
        return json.loads(r.read())


Instruction:
Can you generate the documentation for the following Python 3 function
def send_messages(self, email_messages):
        if not email_messages:
            return
        sent = self._send(email_messages)
        if sent:
            return len(email_messages)
        return 0

Response: Sends one or more EmailMessage objects and returns the number of messages sent.


Instruction:
How would you explain what the following Python 3 function does
def _build_message(self, message):
        if not message.recipients():
            return False
        recipients = ','.join(message.to)
        recipients_cc = ','.join(message.cc)
        recipients_bcc = ','.join(message.bcc)

        text_body = message.body
        html_body = None
        if isinstance(message, EmailMultiAlternatives):
            for alt in message.alternatives:
                if alt[1] == "text/html":
                    html_body = alt[0]
                    break

        elif getattr(message, 'content_subtype', None) == 'html':
            # Don't send html content as plain text
            text_body = None
            html_body = message.body

        reply_to = ','.join(message.reply_to)
        custom_headers = {}
        if message.extra_headers and isinstance(message.extra_headers, dict):
            if 'Reply-To' in message.extra_headers:
                reply_to = message.extra_headers.pop('Reply-To')
            if len(message.extra_headers):
                custom_headers = message.extra_headers
        attachments = []
        if message.attachments and isinstance(message.attachments, list):
            if len(message.attachments):
                for item in message.attachments:
                    if isinstance(item, tuple):
                        (f, content, m) = item
                        content = base64.b64encode(content)
                        # b64decode returns bytes on Python 3. PMMail needs a
                        # str (for JSON serialization). Convert on Python 3
                        # only to avoid a useless performance hit on Python 2.
                        if not isinstance(content, str):
                            content = content.decode()
                        attachments.append((f, content, m))
                    else:
                        attachments.append(item)

        postmark_message = PMMail(api_key=self.api_key,
                                  subject=message.subject,
                                  sender=message.from_email,
                                  to=recipients,
                                  cc=recipients_cc,
                                  bcc=recipients_bcc,
                                  text_body=text_body,
                                  html_body=html_body,
                                  reply_to=reply_to,
                                  custom_headers=custom_headers,
                                  attachments=attachments)

        postmark_message.tag = getattr(message, 'tag', None)
        postmark_message.track_opens = getattr(message, 'track_opens', False)

        return postmark_message

Response: Convert a PMEmailMessage to a PMMail object.


Instruction:
Can you tell what is the following Python 3 function doing
def handle_starttag(self, tag, attrs):
    '''
    PDF link handler; never gets explicitly called by user
    '''
    if tag == 'a' and ( ('class', 'download-pdf') in attrs or ('id', 'download-pdf') in attrs ):
        for attr in attrs:
          if attr[0] == 'href':
            self.download_link = 'http://www.nature.com' + attr[1]

Response: handle_starttag - Handle start tag of the PDF link


Instruction:
Can you write a function in Python 3 where it
generates a password with random chararcters

Response:
def genpass(pattern=r'[\w]{32}'):
    """generates a password with random chararcters
    """
    try:
        return rstr.xeger(pattern)
    except re.error as e:
        raise ValueError(str(e))


Instruction:
Can you generate the documentation for the following Python 3 function
def unpack(self, string):
        if string is None:
            string = CHAR_ZERO * self.__size__
        data = struct.unpack(self.__fmt__, string)
        i = 0
        for field in self.__fields__:
            (vtype, vlen) = self.__fields_types__[field]
            if vtype == 'char': # string
                setattr(self, field, data[i])
                i = i + 1
            elif isinstance(vtype, CStructMeta):
                num = int(vlen / vtype.size)
                if num == 1: # single struct
                    sub_struct = vtype()
                    sub_struct.unpack(EMPTY_BYTES_STRING.join(data[i:i+sub_struct.size]))
                    setattr(self, field, sub_struct)
                    i = i + sub_struct.size
                else: # multiple struct
                    sub_structs = []
                    for j in range(0, num):
                        sub_struct = vtype()
                        sub_struct.unpack(EMPTY_BYTES_STRING.join(data[i:i+sub_struct.size]))
                        i = i + sub_struct.size
                        sub_structs.append(sub_struct)
                    setattr(self, field, sub_structs)
            elif vlen == 1:
                setattr(self, field, data[i])
                i = i + vlen
            else:
                setattr(self, field, list(data[i:i+vlen]))
                i = i + vlen

Response: Unpack the string containing packed C structure data into the object.


Instruction:
Create a Python 3 function for
packing the structure data into a string

Response:
def pack(self):
        """
        Pack the structure data into a string
        """
        data = []
        for field in self.__fields__:
            (vtype, vlen) = self.__fields_types__[field]
            if vtype == 'char': # string
                data.append(getattr(self, field))
            elif isinstance(vtype, CStructMeta):
                num = int(vlen / vtype.size)
                if num == 1: # single struct
                    v = getattr(self, field, vtype())
                    v = v.pack()
                    if sys.version_info >= (3, 0):
                        v = ([bytes([x]) for x in v])
                    data.extend(v)
                else: # multiple struct
                    values = getattr(self, field, [])
                    for j in range(0, num):
                        try:
                            v = values[j]
                        except:
                            v = vtype()
                        v = v.pack()
                        if sys.version_info >= (3, 0):
                            v = ([bytes([x]) for x in v])
                        data.extend(v)
            elif vlen == 1:
                data.append(getattr(self, field))
            else:
                v = getattr(self, field)
                v = v[:vlen] + [0] * (vlen - len(v))
                data.extend(v)
        return struct.pack(self.__fmt__, *data)


Instruction:
How would you code a function in Python 3 to
print info about the current object.

Response:
def print_info(self):
        "andreax  + pts/0        2013-08-21 08:58   .         32341 (l26.box)"
        "           pts/34       2013-06-12 15:04             26396 id=s/34  term=0 exit=0"
#        if self.ut_type not in [6,7]:
#            return
        print("%-10s %-12s %15s %15s %-8s" % (
                    str_from_c(self.ut_user),
                    str_from_c(self.ut_line),
                    time.strftime("%Y-%m-%d %H:%M", time.gmtime(self.ut_tv.tv_sec)),
                    self.ut_pid,
                    str_from_c(self.ut_host) and "(%s)" % str_from_c(self.ut_host) or str_from_c(self.ut_id) and "id=%s" % str_from_c(self.ut_id) or ""))


Instruction:
Write a Python 3 script to
get all subclasses of BaseImporter from module and return and generator

Response:
def get_all():
    """Get all subclasses of BaseImporter from module and return and generator
    """

    _import_all_importer_files()

    for module in (value for key, value in globals().items()
                   if key in __all__):
        for klass_name, klass in inspect.getmembers(module, inspect.isclass):
            if klass is not BaseImporter and issubclass(klass, BaseImporter):
                yield klass

    for klass in _get_importers_from_entry_points():
        yield klass


Instruction:
How would you explain what the following Python 3 function does
def list_database(db):
    credentials = db.credentials()
    if credentials:
        table = Table(
            db.config['headers'],
            table_format=db.config['table_format'],
            colors=db.config['colors'],
            hidden=db.config['hidden'],
            hidden_string=db.config['hidden_string'],
        )
        click.echo(table.render(credentials))

Response: Print credential as a table


Instruction:
Can you create a Python 3 function that
shows current configuration for shell

Response:
def check_config(db, level):
    """Show current configuration for shell"""
    if level == 'global':
        configuration = config.read(config.HOMEDIR, '.passpierc')
    elif level == 'local':
        configuration = config.read(os.path.join(db.path))
    elif level == 'current':
        configuration = db.config

    if configuration:
        click.echo(yaml.safe_dump(configuration, default_flow_style=False))


Instruction:
How would you explain what the following Python 3 function does
def process(self, data=None, **kwargs):
        self.data = self.handle(data, **kwargs)
        return self

Response:
Process the provided data and invoke the handler method for this
           .


Instruction:
Write a Python 3 script to
fetch incoming data from the Flask request object when no data is supplied is assumed to be JSON.

Response:
def process(self, data=None):
        """Fetch incoming data from the Flask request object when no data is supplied
        to the process method.  By default, the RequestHandler expects the
        incoming data to be sent as JSON.
        """

        return super(RequestHandler, self).process(data=data or self.get_request_data())


Instruction:
Can you tell what is the following Python 3 function doing
def save(self, obj):
        session = self.get_db_session()
        session.add(obj)
        session.commit()

        return obj

Response:
Save the object to the SQLAlchemy database and commit the changes back to
        the database.


Instruction:
Given the following Python 3 function, write the documentation
def filter_by_id(self, query):
        if self.model is None:
            raise ArrestedException('DBObjectMixin requires a model to be set.')

        idfield = getattr(self.model, self.model_id_param, None)
        if not idfield:
            raise ArrestedException('DBObjectMixin could not find a valid Model.id.')

        return query.filter(idfield == self.kwargs[self.url_id_param])

Response:
Apply the primary key filter to query to filter the results for a specific
        instance by id.


Instruction:
Implement a function in Python 3 to
implement the GetObjectMixin interface and calls the DBALchemy Query method to get the object.

Response:
def get_object(self):
        """Implements the GetObjectMixin interface and calls
        :meth:`DBObjectMixin.get_query`.  Using this mixin requires usage of
        a response handler capable of serializing SQLAlchemy query result objects.

        :returns: Typically a SQLALchemy Query result.
        :rtype: mixed

        .. seealso::
            :meth:`DBObjectMixin.get_query`
            :meth:`DBObjectMixin.filter_by_id`
            :meth:`DBObjectMixin.get_result`
        """

        query = self.get_query()
        query = self.filter_by_id(query)
        return self.get_result(query)


Instruction:
Can you generate the documentation for the following Python 3 function
def delete_object(self, obj):
        session = self.get_db_session()
        session.delete(obj)
        session.commit()

Response:
Deletes an object from the session by calling session. delete and then commits
        the changes to the database.


Instruction:
Here you have a function in Python 3, explain what it does
def init_app(self, app):

        self.app = app
        if self.deferred:
            self.register_all(self.deferred)

Response: Initialise the ArrestedAPI object by storing a pointer to a Flask app object.


Instruction:
Given the following Python 3 function, write the documentation
def register_resource(self, resource, defer=False):
        if defer:
            self.deferred.append(resource)
        else:
            resource.init_api(self)
            self.app.register_blueprint(resource, url_prefix=self.url_prefix)

Response: Register a resource against the Arrested API.


Instruction:
Implement a function in Python 3 to
process the list of before_{method}_hooks and the before_all_hooks.

Response:
def process_before_request_hooks(self):
        """Process the list of before_{method}_hooks and the before_all_hooks. The hooks
        will be processed in the following order

        1 - any before_all_hooks defined on the :class:`arrested.ArrestedAPI` object
        2 - any before_all_hooks defined on the :class:`arrested.Resource` object
        3 - any before_all_hooks defined on the :class:`arrested.Endpoint` object
        4 - any before_{method}_hooks defined on the :class:`arrested.Endpoint` object
        """

        hooks = []

        if self.resource:
            hooks.extend(self.resource.api.before_all_hooks)
            hooks.extend(self.resource.before_all_hooks)

        hooks.extend(self.before_all_hooks)
        hooks.extend(
            getattr(
                self,
                'before_{method}_hooks'.format(method=self.meth),
                []
            )
        )

        for hook in chain(hooks):
            hook(self)


Instruction:
How would you implement a function in Python 3 that
processes the list of before_{method}_hooks and the after_all_hooks.

Response:
def process_after_request_hooks(self, resp):
        """Process the list of before_{method}_hooks and the before_all_hooks. The hooks
        will be processed in the following order

        1 - any after_{method}_hooks defined on the :class:`arrested.Endpoint` object
        2 - any after_all_hooks defined on the :class:`arrested.Endpoint` object
        2 - any after_all_hooks defined on the :class:`arrested.Resource` object
        4 - any after_all_hooks defined on the :class:`arrested.ArrestedAPI` object
        """

        hooks = []
        meth_hooks = getattr(
            self,
            'after_{method}_hooks'.format(method=self.meth),
            []
        )

        hooks.extend(meth_hooks)
        hooks.extend(self.after_all_hooks)

        if self.resource:
            hooks.extend(self.resource.after_all_hooks)
            hooks.extend(self.resource.api.after_all_hooks)

        for hook in chain(hooks):
            resp = hook(self, resp)

        return resp


Instruction:
Can you implement a function in Python 3 that
dispatches the incoming HTTP request to the appropriate handler.

Response:
def dispatch_request(self, *args, **kwargs):
        """Dispatch the incoming HTTP request to the appropriate handler.
        """
        self.args = args
        self.kwargs = kwargs
        self.meth = request.method.lower()
        self.resource = current_app.blueprints.get(request.blueprint, None)

        if not any([self.meth in self.methods, self.meth.upper() in self.methods]):
            return self.return_error(405)

        self.process_before_request_hooks()

        resp = super(Endpoint, self).dispatch_request(*args, **kwargs)
        resp = self.make_response(resp)

        resp = self.process_after_request_hooks(resp)

        return resp


Instruction:
Can you write a function in Python 3 where it
creates a response object from the given response value.

Response:
def make_response(self, rv, status=200, headers=None, mime='application/json'):
        """Create a response object using the :class:`flask.Response` class.

        :param rv: Response value.  If the value is not an instance
            of :class:`werkzeug.wrappers.Response` it will be converted
            into a Response object.
        :param status: specify the HTTP status code for this response.
        :param mime: Specify the mimetype for this request.
        :param headers: Specify dict of headers for the response.

        """
        if not isinstance(rv, Response):
            resp = Response(
                response=rv,
                headers=headers,
                mimetype=mime,
                status=status
            )
        else:
            resp = rv

        return resp


Instruction:
Given the following Python 3 function, write the documentation
def get_response_handler(self):
        assert self.response_handler is not None, \
            'Please define a response_handler ' \
            ' for Endpoint: %s' % self.__class__.__name__

        return self.response_handler(self, **self.get_response_handler_params())

Response: Returns the Endpoints defined : attr : Endpoint. response_handler.


Instruction:
How would you explain what the following Python 3 function does
def get_request_handler(self):
        assert self.request_handler is not None, \
            'Please define a request_handler ' \
            ' for Endpoint: %s' % self.__class__.__name__

        return self.request_handler(self, **self.get_request_handler_params())

Response: Returns the Endpoint s request_handler function.


Instruction:
Given the following Python 3 function, write the documentation
def handle(self, data, **kwargs):
        if self.many:
            return self.mapper.many(raw=self.raw, **self.mapper_kwargs).serialize(
                data, role=self.role
            )
        else:
            return self.mapper(obj=data, raw=self.raw, **self.mapper_kwargs).serialize(
                role=self.role
            )

Response: Run serialization for the specified mapper_class.


Instruction:
Given the following Python 3 function, write the documentation
def handle_error(self, exp):
        payload = {
            "message": "Invalid or incomplete data provided.",
            "errors": exp.errors
        }
        self.endpoint.return_error(self.error_status, payload=payload)

Response: Called if a Mapper returns an error. Should handle the error and return it in the appropriate format.


Instruction:
Write a Python 3 script to
run marshalling for the specified mapper_class.

Response:
def handle(self, data, **kwargs):
        """Run marshalling for the specified mapper_class.

        Supports both .marshal and .many().marshal Kim interfaces.  Handles errors raised
        during marshalling and automatically returns a HTTP error response.

        :param data: Data to be marshaled.
        :returns: Marshaled object according to mapper configuration
        :raises: :class:`werkzeug.exceptions.UnprocessableEntity`
        """
        try:
            if self.many:
                return self.mapper.many(raw=self.raw, **self.mapper_kwargs).marshal(
                    data, role=self.role
                )
            else:
                return self.mapper(
                    data=data,
                    obj=self.obj,
                    partial=self.partial,
                    **self.mapper_kwargs
                ).marshal(role=self.role)
        except MappingInvalid as e:
            self.handle_error(e)


Instruction:
Can you write a function in Python 3 where it
returns a dictionary that will be used to configure the KimResponseHandler

Response:
def get_response_handler_params(self, **params):
        """Return a config object that will be used to configure the KimResponseHandler

        :returns: a dictionary of config options
        :rtype: dict
        """

        params = super(KimEndpoint, self).get_response_handler_params(**params)
        params['mapper_class'] = self.mapper_class
        params['role'] = self.serialize_role

        # After a successfull attempt to marshal an object has been made, a response
        # is generated using the RepsonseHandler.  Rather than taking the class level
        # setting for many by default, pull it from the request handler params config to
        # ensure Marshaling and Serializing are run the same way.
        if self._is_marshal_request():
            req_params = self.get_request_handler_params()
            params['many'] = req_params.get('many', self.many)
        else:
            params['many'] = self.many

        return params


Instruction:
How would you explain what the following Python 3 function does
def get_request_handler_params(self, **params):

        params = super(KimEndpoint, self).get_request_handler_params(**params)
        params['mapper_class'] = self.mapper_class
        params['role'] = self.marshal_role
        params['many'] = False
        # when handling a PUT or PATCH request, self.obj will be set.. There might be a
        # more robust way to handle this?
        params['obj'] = getattr(self, 'obj', None)
        params['partial'] = self.is_partial()

        return params

Response: Return a dictionary of config object that will be used to configure the KimRequestHandler


Instruction:
Can you implement a function in Python 3 that
pulls the processed data from the response_handler and return a response.

Response:
def list_response(self, status=200):
        """Pull the processed data from the response_handler and return a response.

        :param status: The HTTP status code returned with the response

        .. seealso:
            :meth:`Endpoint.make_response`
            :meth:`Endpoint.handle_get_request`
        """

        return self._response(self.response.get_response_data(), status=status)


Instruction:
Implement a Python 3 function for
handling incoming GET requests to an Endpoint and return an array of results by calling self. list_response.

Response:
def handle_get_request(self):
        """Handle incoming GET request to an Endpoint and return an
        array of results by calling :meth:`.GetListMixin.get_objects`.

        .. seealso::
            :meth:`GetListMixin.get_objects`
            :meth:`Endpoint.get`
        """
        self.objects = self.get_objects()
        self.response = self.get_response_handler()

        self.response.process(self.objects)

        return self.list_response()


Instruction:
Given the following Python 3 function, write the documentation
def create_response(self, status=201):
        self.response = self.get_response_handler()
        self.response.process(self.obj)

        return self._response(self.response.get_response_data(), status=status)

Response: Generate a Response object for a POST request.


Instruction:
Write a Python 3 function that can
handle incoming POST request to an Endpoint and marshal the request data

Response:
def handle_post_request(self):
        """Handle incoming POST request to an Endpoint and marshal the request data
        via the specified RequestHandler.  :meth:`.CreateMixin.save_object`. is then
        called and must be implemented by mixins implementing this interfce.

        .. seealso::
            :meth:`CreateMixin.save_object`
            :meth:`Endpoint.post`
        """
        self.request = self.get_request_handler()
        self.obj = self.request.process().data

        self.save_object(self.obj)
        return self.create_response()


Instruction:
Can you generate a brief explanation for the following Python 3 code
def obj(self):
        if not getattr(self, '_obj', None):
            self._obj = self.get_object()
            if self._obj is None and not self.allow_none:
                self.return_error(404)

        return self._obj

Response:
Returns the value of ObjectMixin. get_object and sets a private
        property called _obj.


Instruction:
Write a Python 3 script for
crawling several FSMs in parallel, mapping the states of a larger meta-FSM. To determine whether a state in the larger FSM is final, pass all of the finality statuses (e.g. [True, False, False] to `test`.

Response:
def parallel(fsms, test):
	'''
		Crawl several FSMs in parallel, mapping the states of a larger meta-FSM.
		To determine whether a state in the larger FSM is final, pass all of the
		finality statuses (e.g. [True, False, False] to `test`.
	'''
	alphabet = set().union(*[fsm.alphabet for fsm in fsms])

	initial = dict([(i, fsm.initial) for (i, fsm) in enumerate(fsms)])

	# dedicated function accepts a "superset" and returns the next "superset"
	# obtained by following this transition in the new FSM
	def follow(current, symbol):
		next = {}
		for i in range(len(fsms)):
			if symbol not in fsms[i].alphabet and anything_else in fsms[i].alphabet:
				actual_symbol = anything_else
			else:
				actual_symbol = symbol
			if i in current \
			and current[i] in fsms[i].map \
			and actual_symbol in fsms[i].map[current[i]]:
				next[i] = fsms[i].map[current[i]][actual_symbol]
		if len(next.keys()) == 0:
			raise OblivionError
		return next

	# Determine the "is final?" condition of each substate, then pass it to the
	# test to determine finality of the overall FSM.
	def final(state):
		accepts = [i in state and state[i] in fsm.finals for (i, fsm) in enumerate(fsms)]
		return test(accepts)

	return crawl(alphabet, initial, final, follow).reduce()


Instruction:
How would you explain what the following Python 3 function does
def crawl(alphabet, initial, final, follow):
	'''
		Given the above conditions and instructions, crawl a new unknown FSM,
		mapping its states, final states and transitions. Return the new FSM.
		This is a pretty powerful procedure which could potentially go on
		forever if you supply an evil version of follow().
	'''

	states = [initial]
	finals = set()
	map = {}

	# iterate over a growing list
	i = 0
	while i < len(states):
		state = states[i]

		# add to finals
		if final(state):
			finals.add(i)

		# compute map for this state
		map[i] = {}
		for symbol in sorted(alphabet, key=key):
			try:
				next = follow(state, symbol)

				try:
					j = states.index(next)
				except ValueError:
					j = len(states)
					states.append(next)

			except OblivionError:
				# Reached an oblivion state. Don't list it.
				continue

			map[i][symbol] = j

		i += 1

	return fsm(
		alphabet = alphabet,
		states   = range(len(states)),
		initial  = 0,
		finals   = finals,
		map      = map,
	)

Response: This function is a pretty powerful procedure which can be used to crawl unknown FSM states and transitions.


Instruction:
Can you tell what is the following Python 3 function doing
def accepts(self, input):
		'''
			Test whether the present FSM accepts the supplied string (iterable of
			symbols). Equivalently, consider `self` as a possibly-infinite set of
			strings and test whether `string` is a member of it.
			This is actually mainly used for unit testing purposes.
			If `fsm.anything_else` is in your alphabet, then any symbol not in your
			alphabet will be converted to `fsm.anything_else`.
		'''
		state = self.initial
		for symbol in input:
			if anything_else in self.alphabet and not symbol in self.alphabet:
				symbol = anything_else

			# Missing transition = transition to dead state
			if not (state in self.map and symbol in self.map[state]):
				return False

			state = self.map[state][symbol]
		return state in self.finals

Response: Tests whether the present FSM accepts the supplied string.


Instruction:
Can you tell what is the following Python 3 function doing
def concatenate(*fsms):
		'''
			Concatenate arbitrarily many finite state machines together.
		'''
		alphabet = set().union(*[fsm.alphabet for fsm in fsms])

		def connect_all(i, substate):
			'''
				Take a state in the numbered FSM and return a set containing it, plus
				(if it's final) the first state from the next FSM, plus (if that's
				final) the first state from the next but one FSM, plus...
			'''
			result = {(i, substate)}
			while i < len(fsms) - 1 and substate in fsms[i].finals:
				i += 1
				substate = fsms[i].initial
				result.add((i, substate))
			return result

		# Use a superset containing states from all FSMs at once.
		# We start at the start of the first FSM. If this state is final in the
		# first FSM, then we are also at the start of the second FSM. And so on.
		initial = set()
		if len(fsms) > 0:
			initial.update(connect_all(0, fsms[0].initial))
		initial = frozenset(initial)

		def final(state):
			'''If you're in a final state of the final FSM, it's final'''
			for (i, substate) in state:
				if i == len(fsms) - 1 and substate in fsms[i].finals:
					return True
			return False

		def follow(current, symbol):
			'''
				Follow the collection of states through all FSMs at once, jumping to the
				next FSM if we reach the end of the current one
				TODO: improve all follow() implementations to allow for dead metastates?
			'''
			next = set()
			for (i, substate) in current:
				fsm = fsms[i]
				if substate in fsm.map and symbol in fsm.map[substate]:
					next.update(connect_all(i, fsm.map[substate][symbol]))
			if len(next) == 0:
				raise OblivionError
			return frozenset(next)

		return crawl(alphabet, initial, final, follow).reduce()

Response: Concatenate arbitrarily many finite state machines together.


Instruction:
Create a Python 3 function to
return an FSM that accepts X returns an FSM accepting X *

Response:
def star(self):
		'''
			If the present FSM accepts X, returns an FSM accepting X* (i.e. 0 or
			more Xes). This is NOT as simple as naively connecting the final states
			back to the initial state: see (b*ab)* for example.
		'''
		alphabet = self.alphabet

		initial = {self.initial}

		def follow(state, symbol):
			next = set()
			for substate in state:
				if substate in self.map and symbol in self.map[substate]:
					next.add(self.map[substate][symbol])

				# If one of our substates is final, then we can also consider
				# transitions from the initial state of the original FSM.
				if substate in self.finals \
				and self.initial in self.map \
				and symbol in self.map[self.initial]:
					next.add(self.map[self.initial][symbol])

			if len(next) == 0:
				raise OblivionError

			return frozenset(next)

		def final(state):
			return any(substate in self.finals for substate in state)

		return crawl(alphabet, initial, final, follow) | epsilon(alphabet)


Instruction:
Can you create a Python 3 function that
gives an FSM and a multiplier, return the multiplied FSM.

Response:
def times(self, multiplier):
		'''
			Given an FSM and a multiplier, return the multiplied FSM.
		'''
		if multiplier < 0:
			raise Exception("Can't multiply an FSM by " + repr(multiplier))

		alphabet = self.alphabet

		# metastate is a set of iterations+states
		initial = {(self.initial, 0)}

		def final(state):
			'''If the initial state is final then multiplying doesn't alter that'''
			for (substate, iteration) in state:
				if substate == self.initial \
				and (self.initial in self.finals or iteration == multiplier):
					return True
			return False

		def follow(current, symbol):
			next = []
			for (substate, iteration) in current:
				if iteration < multiplier \
				and substate in self.map \
				and symbol in self.map[substate]:
					next.append((self.map[substate][symbol], iteration))
					# final of self? merge with initial on next iteration
					if self.map[substate][symbol] in self.finals:
						next.append((self.initial, iteration + 1))
			if len(next) == 0:
				raise OblivionError
			return frozenset(next)

		return crawl(alphabet, initial, final, follow).reduce()


Instruction:
How would you implement a function in Python 3 that
returns a finite state machine which will accept any string NOT accepted by self and will not accept any string NOT accepted by self.

Response:
def everythingbut(self):
		'''
			Return a finite state machine which will accept any string NOT
			accepted by self, and will not accept any string accepted by self.
			This is more complicated if there are missing transitions, because the
			missing "dead" state must now be reified.
		'''
		alphabet = self.alphabet

		initial = {0 : self.initial}

		def follow(current, symbol):
			next = {}
			if 0 in current and current[0] in self.map and symbol in self.map[current[0]]:
				next[0] = self.map[current[0]][symbol]
			return next

		# state is final unless the original was
		def final(state):
			return not (0 in state and state[0] in self.finals)

		return crawl(alphabet, initial, final, follow).reduce()


Instruction:
Given the following Python 3 function, write the documentation
def reversed(self):
		'''
			Return a new FSM such that for every string that self accepts (e.g.
			"beer", the new FSM accepts the reversed string ("reeb").
		'''
		alphabet = self.alphabet

		# Start from a composite "state-set" consisting of all final states.
		# If there are no final states, this set is empty and we'll find that
		# no other states get generated.
		initial = frozenset(self.finals)

		# Find every possible way to reach the current state-set
		# using this symbol.
		def follow(current, symbol):
			next = frozenset([
				prev
				for prev in self.map
				for state in current
				if symbol in self.map[prev] and self.map[prev][symbol] == state
			])
			if len(next) == 0:
				raise OblivionError
			return next

		# A state-set is final if the initial state is in it.
		def final(state):
			return self.initial in state

		# Man, crawl() is the best!
		return crawl(alphabet, initial, final, follow)

Response: Returns a new FSM that accepts the reversed string.


Instruction:
Here you have a function in Python 3, explain what it does
def strings(self):
		'''
			Generate strings (lists of symbols) that this FSM accepts. Since there may
			be infinitely many of these we use a generator instead of constructing a
			static list. Strings will be sorted in order of length and then lexically.
			This procedure uses arbitrary amounts of memory but is very fast. There
			may be more efficient ways to do this, that I haven't investigated yet.
			You can use this in list comprehensions.
		'''

		# Many FSMs have "dead states". Once you reach a dead state, you can no
		# longer reach a final state. Since many strings may end up here, it's
		# advantageous to constrain our search to live states only.
		livestates = set(state for state in self.states if self.islive(state))

		# We store a list of tuples. Each tuple consists of an input string and the
		# state that this input string leads to. This means we don't have to run the
		# state machine from the very beginning every time we want to check a new
		# string.
		strings = []

		# Initial entry (or possibly not, in which case this is a short one)
		cstate = self.initial
		cstring = []
		if cstate in livestates:
			if cstate in self.finals:
				yield cstring
			strings.append((cstring, cstate))

		# Fixed point calculation
		i = 0
		while i < len(strings):
			(cstring, cstate) = strings[i]
			if cstate in self.map:
				for symbol in sorted(self.map[cstate], key=key):
					nstate = self.map[cstate][symbol]
					nstring = cstring + [symbol]
					if nstate in livestates:
						if nstate in self.finals:
							yield nstring
						strings.append((nstring, nstate))
			i += 1

Response: Yields all the strings that this FSM accepts.


Instruction:
Explain what the following Python 3 code does
def cardinality(self):
		'''
			Consider the FSM as a set of strings and return the cardinality of that
			set, or raise an OverflowError if there are infinitely many
		'''
		num_strings = {}
		def get_num_strings(state):
			# Many FSMs have at least one oblivion state
			if self.islive(state):
				if state in num_strings:
					if num_strings[state] is None: # "computing..."
						# Recursion! There are infinitely many strings recognised
						raise OverflowError(state)
					return num_strings[state]
				num_strings[state] = None # i.e. "computing..."

				n = 0
				if state in self.finals:
					n += 1
				if state in self.map:
					for symbol in self.map[state]:
						n += get_num_strings(self.map[state][symbol])
				num_strings[state] = n

			else:
				# Dead state
				num_strings[state] = 0

			return num_strings[state]

		return get_num_strings(self.initial)

Response: Returns the cardinality of the FSM.


Instruction:
Make a summary of the following Python 3 code
def copy(self):
		'''
			For completeness only, since `set.copy()` also exists. FSM objects are
			immutable, so I can see only very odd reasons to need this.
		'''
		return fsm(
			alphabet = self.alphabet,
			states   = self.states,
			initial  = self.initial,
			finals   = self.finals,
			map      = self.map,
		)

Response: Returns a copy of the FSM.


Instruction:
Given the following Python 3 function, write the documentation
def derive(self, input):
		'''
			Compute the Brzozowski derivative of this FSM with respect to the input
			string of symbols. <https://en.wikipedia.org/wiki/Brzozowski_derivative>
			If any of the symbols are not members of the alphabet, that's a KeyError.
			If you fall into oblivion, then the derivative is an FSM accepting no
			strings.
		'''
		try:
			# Consume the input string.
			state = self.initial
			for symbol in input:
				if not symbol in self.alphabet:
					if not anything_else in self.alphabet:
						raise KeyError(symbol)
					symbol = anything_else

				# Missing transition = transition to dead state
				if not (state in self.map and symbol in self.map[state]):
					raise OblivionError

				state = self.map[state][symbol]

			# OK so now we have consumed that string, use the new location as the
			# starting point.
			return fsm(
				alphabet = self.alphabet,
				states   = self.states,
				initial  = state,
				finals   = self.finals,
				map      = self.map,
			)

		except OblivionError:
			# Fell out of the FSM. The derivative of this FSM is the empty FSM.
			return null(self.alphabet)

Response: Derive the state of this FSM from the input string.


Instruction:
Write a Python 3 script for
registering an endpoint aginst this resource.

Response:
def add_endpoint(self, endpoint):
        """Register an :class:`.Endpoint` aginst this resource.

        :param endpoint: :class:`.Endpoint` API Endpoint class

        Usage::

            foo_resource = Resource('example', __name__)
            class MyEndpoint(Endpoint):

                url = '/example'
                name = 'myendpoint'

            foo_resource.add_endpoint(MyEndpoint)
        """

        if self.url_prefix:
            url = '{prefix}{url}'.format(prefix=self.url_prefix, url=endpoint.url)
        else:
            url = endpoint.url

        self.add_url_rule(
            url,
            view_func=endpoint.as_view(endpoint.get_name()),
        )


Instruction:
Can you implement a function in Python 3 that
reduces the result of this method call ( unless you already reduced it.

Response:
def reduce_after(method):
	'''reduce() the result of this method call (unless you already reduced it).'''
	def new_method(self, *args, **kwargs):
		result = method(self, *args, **kwargs)
		if result == self:
			return result
		return result.reduce()
	return new_method


Instruction:
Can you generate the documentation for the following Python 3 function
def call_fsm(method):
	'''
		Take a method which acts on 0 or more regular expression objects... return a
		new method which simply converts them all to FSMs, calls the FSM method
		on them instead, then converts the result back to a regular expression.
		We do this for several of the more annoying operations.
	'''
	fsm_method = getattr(fsm.fsm, method.__name__)
	def new_method(*legos):
		alphabet = set().union(*[lego.alphabet() for lego in legos])
		return from_fsm(fsm_method(*[lego.to_fsm(alphabet) for lego in legos]))
	return new_method

Response: A method which converts all of the given legos to FSMs and returns a new method which simply calls the FSM methodon them instead.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def from_fsm(f):
	'''
		Turn the supplied finite state machine into a `lego` object. This is
		accomplished using the Brzozowski algebraic method.
	'''
	# Make sure the supplied alphabet is kosher. It must contain only single-
	# character strings or `fsm.anything_else`.
	for symbol in f.alphabet:
		if symbol == fsm.anything_else:
			continue
		if isinstance(symbol, str) and len(symbol) == 1:
			continue
		raise Exception("Symbol " + repr(symbol) + " cannot be used in a regular expression")

	# We need a new state not already used
	outside = object()

	# The set of strings that would be accepted by this FSM if you started
	# at state i is represented by the regex R_i.
	# If state i has a sole transition "a" to state j, then we know R_i = a R_j.
	# If state i is final, then the empty string is also accepted by this regex.
	# And so on...

	# From this we can build a set of simultaneous equations in len(f.states)
	# variables. This system is easily solved for all variables, but we only
	# need one: R_a, where a is the starting state.

	# The first thing we need to do is organise the states into order of depth,
	# so that when we perform our back-substitutions, we can start with the
	# last (deepest) state and therefore finish with R_a.
	states = [f.initial]
	i = 0
	while i < len(states):
		current = states[i]
		if current in f.map:
			for symbol in sorted(f.map[current], key=fsm.key):
				next = f.map[current][symbol]
				if next not in states:
					states.append(next)
		i += 1

	# Our system of equations is represented like so:
	brz = {}
	for a in f.states:
		brz[a] = {}
		for b in f.states | {outside}:
			brz[a][b] = nothing

	# Populate it with some initial data.
	for a in f.map:
		for symbol in f.map[a]:
			b = f.map[a][symbol]
			if symbol == fsm.anything_else:
				brz[a][b] |= ~charclass(f.alphabet - {fsm.anything_else})
			else:
				brz[a][b] |= charclass({symbol})
		if a in f.finals:
			brz[a][outside] |= emptystring

	# Now perform our back-substitution
	for i in reversed(range(len(states))):
		a = states[i]

		# Before the equation for R_a can be substituted into the other
		# equations, we need to resolve the self-transition (if any).
		# e.g.    R_a = 0 R_a |   1 R_b |   2 R_c
		# becomes R_a =         0*1 R_b | 0*2 R_c
		loop = brz[a][a] * star # i.e. "0*"
		del brz[a][a]

		for right in brz[a]:
			brz[a][right] = loop + brz[a][right]

		# Note: even if we're down to our final equation, the above step still
		# needs to be performed before anything is returned.

		# Now we can substitute this equation into all of the previous ones.
		for j in range(i):
			b = states[j]

			# e.g. substituting R_a =  0*1 R_b |      0*2 R_c
			# into              R_b =    3 R_a |        4 R_c | 5 R_d
			# yields            R_b = 30*1 R_b | (30*2|4) R_c | 5 R_d
			univ = brz[b][a] # i.e. "3"
			del brz[b][a]

			for right in brz[a]:
				brz[b][right] |= univ + brz[a][right]

	return brz[f.initial][outside].reduce()

Response: Convert a finite state machine into a lego object.


Instruction:
Can you tell what is the following Python 3 function doing
def parse(cls, string):
		'''
			Parse the entire supplied string as an instance of the present class.
			Mainly for internal use in unit tests because it drops through to match()
			in a convenient way.
		'''
		obj, i = cls.match(string, 0)
		if i != len(string):
			raise Exception("Could not parse '" + string + "' beyond index " + str(i))
		return obj

Response: Parses the supplied string as an instance of the present class.


Instruction:
Can you generate the documentation for the following Python 3 function
def strings(self, otherchar=None):
		'''
			Each time next() is called on this iterator, a new string is returned
			which will the present lego piece can match. StopIteration is raised once
			all such strings have been returned, although a regex with a * in may
			match infinitely many strings.
		'''

		# In the case of a regex like "[^abc]", there are infinitely many (well, a
		# very large finite number of) single characters which will match. It's not
		# productive to iterate over all of these giving every single example.
		# You must supply your own "otherchar" to stand in for all of these
		# possibilities.
		for string in self.to_fsm().strings():

			# Have to represent `fsm.anything_else` somehow.
			if fsm.anything_else in string:
				if otherchar == None:
					raise Exception("Please choose an 'otherchar'")
				string = [
					otherchar if char == fsm.anything_else else char
					for char in string
				]

			yield "".join(string)

Response: Iterate over the string in this iterator.


Instruction:
Implement a Python 3 function for
returning True if this multipliers can intersect other.

Response:
def canintersect(self, other):
		'''
			Intersection is not well-defined for all pairs of multipliers.
			For example:
				{2,3} & {3,4} = {3}
				{2,} & {1,7} = {2,7}
				{2} & {5} = ERROR
		'''
		return not (self.max < other.min or other.max < self.min)


Instruction:
Implement a function in Python 3 to
return True if this multiplier can be unioned with the other.

Response:
def canunion(self, other):
		'''Union is not defined for all pairs of multipliers. e.g. {0,1} | {3,4}'''
		return not (self.max + bound(1) < other.min or other.max + bound(1) < self.min)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def common(self, other):
		'''
			Find the shared part of two multipliers. This is the largest multiplier
			which can be safely subtracted from both the originals. This may
			return the "zero" multiplier.
		'''
		mandatory = min(self.mandatory, other.mandatory)
		optional = min(self.optional, other.optional)
		return multiplier(mandatory, mandatory + optional)

Response: Find the common part of two multipliers.


Instruction:
Implement a function in Python 3 to
dock self from other and return the result.

Response:
def dock(self, other):
		'''
			"Dock" another mult from this one (i.e. remove part of the tail) and
			return the result. The reverse of concatenation. This is a lot trickier.
			e.g. a{4,5} - a{3} = a{1,2}
		'''
		if other.multiplicand != self.multiplicand:
			raise Exception("Can't subtract " + repr(other) + " from " + repr(self))
		return mult(self.multiplicand, self.multiplier - other.multiplier)


Instruction:
Can you tell what is the following Python 3 function doing
def common(self, other):
		'''
			Return the common part of these two mults. This is the largest mult
			which can be safely subtracted from both the originals. The multiplier
			on this mult could be zero: this is the case if, for example, the
			multiplicands disagree.
		'''
		if self.multiplicand == other.multiplicand:
			return mult(self.multiplicand, self.multiplier.common(other.multiplier))

		# Multiplicands disagree, no common part at all.
		return mult(nothing, zero)

Response: Return the common part of two multiplicands.


Instruction:
Implement a Python 3 function for
returning the common prefix of two multiplicands.

Response:
def common(self, other, suffix=False):
		'''
			Return the common prefix of these two concs; that is, the largest conc
			which can be safely beheaded() from the front of both.
			The result could be emptystring.
			"ZYAA, ZYBB" -> "ZY"
			"CZ, CZ" -> "CZ"
			"YC, ZC" -> ""

			With the "suffix" flag set, works from the end. E.g.:
			"AAZY, BBZY" -> "ZY"
			"CZ, CZ" -> "CZ"
			"CY, CZ" -> ""
		'''
		mults = []

		indices = range(min(len(self.mults), len(other.mults))) # e.g. [0, 1, 2, 3]

		# Work backwards from the end of both concs instead.
		if suffix:
			indices = [-i - 1 for i in indices] # e.g. [-1, -2, -3, -4]

		for i in indices:

			common = self.mults[i].common(other.mults[i])

			# Happens when multiplicands disagree (e.g. "A.common(B)") or if
			# the multiplicand is shared but the common multiplier is zero
			# (e.g. "ABZ*.common(CZ)".)
			if common.multiplier == zero:
				break

			mults.append(common)

			# If we did not remove the entirety of both mults, we cannot continue.
			if common != self.mults[i] or common != other.mults[i]:
				break

		if suffix:
			mults = reversed(mults)

		return conc(*mults)


Instruction:
Write a Python 3 script for
subtracting another conc from this one. This is the opposite of concatenation. For example, if ABC + DEF = ABCDEF, then logically ABCDEF - DEF = ABC.

Response:
def dock(self, other):
		'''
			Subtract another conc from this one.
			This is the opposite of concatenation. For example, if ABC + DEF = ABCDEF,
			then logically ABCDEF - DEF = ABC.
		'''

		# e.g. self has mults at indices [0, 1, 2, 3, 4, 5, 6] len=7
		# e.g. other has mults at indices [0, 1, 2] len=3
		new = list(self.mults)
		for i in reversed(range(len(other.mults))): # [2, 1, 0]
			# e.g. i = 1, j = 7 - 3 + 1 = 5
			j = len(self.mults) - len(other.mults) + i
			new[j] = new[j].dock(other.mults[i])

			if new[j].multiplier == zero:
				# omit that mult entirely since it has been factored out
				del new[j]

			# If the subtraction is incomplete but there is more to
			# other.mults, then we have a problem. For example, "ABC{2} - BC"
			# subtracts the C successfully but leaves something behind,
			# then tries to subtract the B too, which isn't possible
			else:
				if i != 0:
					raise Exception("Can't subtract " + repr(other) + " from " + repr(self))

		return conc(*new)


Instruction:
Can you tell what is the following Python 3 function doing
def dock(self, other):
		'''
			The opposite of concatenation. Remove a common suffix from the present
			pattern; that is, from each of its constituent concs.
			AYZ|BYZ|CYZ - YZ = A|B|C.
		'''
		return pattern(*[c.dock(other) for c in self.concs])

Response:
The opposite of concatenation. Remove common suffix from the present
			pattern.


Instruction:
Can you implement a function in Python 3 that
returns the behead pattern for this node and other.

Response:
def behead(self, other):
		'''
			Like dock() but the other way around. Remove a common prefix from the
			present pattern; that is, from each of its constituent concs.
			ZA|ZB|ZC.behead(Z) = A|B|C
		'''
		return pattern(*[c.behead(other) for c in self.concs])


Instruction:
Can you tell what is the following Python 3 function doing
def _commonconc(self, suffix=False):
		'''
			Find the longest conc which acts as prefix to every conc in this pattern.
			This could be the empty string. Return the common prefix along with all
			the leftovers after truncating that common prefix from each conc.
			"ZA|ZB|ZC" -> "Z", "(A|B|C)"
			"ZA|ZB|ZC|Z" -> "Z", "(A|B|C|)"
			"CZ|CZ" -> "CZ", "()"

			If "suffix" is True, the same result but for suffixes.
		'''
		if len(self.concs) == 0:
			raise Exception("Can't call _commonconc on " + repr(self))

		from functools import reduce
		return reduce(
			lambda x, y: x.common(y, suffix=suffix),
			self.concs
		)

Response: Return the common prefix of each conc of this pattern.


Instruction:
Explain what the following Python 3 code does
def delete_name(name):
    ''' This function don't use the plugin. '''
    session = create_session()
    try:
        user = session.query(User).filter_by(name=name).first()
        session.delete(user)
        session.commit()
    except SQLAlchemyError, e:
        session.rollback()
        raise bottle.HTTPError(500, "Database Error", e)
    finally:
        session.close()

Response: This function don t use the plugin.


Instruction:
How would you explain what the following Python 3 function does
def setup(self, app):
        ''' Make sure that other installed plugins don't affect the same
            keyword argument and check if metadata is available.'''
        for other in app.plugins:
            if not isinstance(other, SQLAlchemyPlugin):
                continue
            if other.keyword == self.keyword:
                raise bottle.PluginError("Found another SQLAlchemy plugin with "\
                                  "conflicting settings (non-unique keyword).")
            elif other.name == self.name:
                self.name += '_%s' % self.keyword
        if self.create and not self.metadata:
            raise bottle.PluginError('Define metadata value to create database.')

Response:
Make sure that other installed plugins don t affect the same
            keyword argument and check if metadata is available.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def send_multipart(self, *args, **kwargs):
        self.__in_send_multipart = True
        try:
            msg = super(GreenSocket, self).send_multipart(*args, **kwargs)
        finally:
            self.__in_send_multipart = False
            self.__state_changed()
        return msg

Response: wrap send_multipart to prevent state_changed on each partial send


Instruction:
Explain what the following Python 3 code does
def recv_multipart(self, *args, **kwargs):
        self.__in_recv_multipart = True
        try:
            msg = super(GreenSocket, self).recv_multipart(*args, **kwargs)
        finally:
            self.__in_recv_multipart = False
            self.__state_changed()
        return msg

Response: wrap recv_multipart to prevent state_changed on each partial recv


Instruction:
Can you tell what is the following Python 3 function doing
def load_all(path, include_core=True, subfolders=None, path_in_arc=None):
    def clean(varStr):
        """ get valid python name from folder
        """
        return re.sub('\W|^(?=\d)', '_', str(varStr))

    path = Path(path)

    if zipfile.is_zipfile(str(path)):
        with zipfile.ZipFile(file=str(path), mode='r') as zz:
            zipcontent = zz.namelist()
        if path_in_arc:
            path_in_arc = str(path_in_arc)
            if path_in_arc not in zipcontent:
                path_in_arc = os.path.join(path_in_arc,
                                           DEFAULT_FILE_NAMES['filepara'])
                if path_in_arc not in zipcontent:
                    raise ReadError('File parameter file {} not found in {}. '
                                    'Tip: specify fileparameter filename '
                                    'through "path_in_arc" if different '
                                    'from default.'.format(
                                        DEFAULT_FILE_NAMES['filepara'], path))

        else:
            with zipfile.ZipFile(file=str(path), mode='r') as zz:
                fpfiles = [
                    f for f in zz.namelist()
                    if
                    os.path.basename(f) == DEFAULT_FILE_NAMES['filepara'] and
                    json.loads(zz.read(f).decode('utf-8')
                               )['systemtype'] == 'IOSystem']
            if len(fpfiles) == 0:
                raise ReadError('File parameter file {} not found in {}. '
                                'Tip: specify fileparameter filename '
                                'through "path_in_arc" if different '
                                'from default.'.format(
                                    DEFAULT_FILE_NAMES['filepara'], path))
            elif len(fpfiles) > 1:
                raise ReadError('Mulitple mrio archives found in {}. '
                                'Specify one by the '
                                'parameter "path_in_arc"'.format(path))
            else:
                path_in_arc = os.path.dirname(fpfiles[0])

        logging.debug("Expect file parameter-file at {} in {}".format(
            path_in_arc, path))

    io = load(path, include_core=include_core, path_in_arc=path_in_arc)

    if zipfile.is_zipfile(str(path)):
        root_in_zip = os.path.dirname(path_in_arc)
        if subfolders is None:
            subfolders = {
                os.path.relpath(os.path.dirname(p), root_in_zip)
                for p in zipcontent
                if p.startswith(root_in_zip) and
                os.path.dirname(p) != root_in_zip}

        for subfolder_name in subfolders:
            if subfolder_name not in zipcontent + list({
                    os.path.dirname(p) for p in zipcontent}):
                subfolder_full = os.path.join(root_in_zip, subfolder_name)
            else:
                subfolder_full = subfolder_name
            subfolder_name = os.path.basename(os.path.normpath(subfolder_name))

            if subfolder_name not in zipcontent:
                subfolder_full_meta = os.path.join(
                    subfolder_full, DEFAULT_FILE_NAMES['filepara'])
            else:
                subfolder_full_meta = subfolder_full

            if subfolder_full_meta in zipcontent:
                ext = load(path,
                           include_core=include_core,
                           path_in_arc=subfolder_full_meta)
                setattr(io, clean(subfolder_name), ext)
                io.meta._add_fileio("Added satellite account "
                                    "from {}".format(subfolder_full))
            else:
                continue

    else:
        if subfolders is None:
            subfolders = [d for d in path.iterdir() if d.is_dir()]

        for subfolder_name in subfolders:
            if not os.path.exists(str(subfolder_name)):
                subfolder_full = path / subfolder_name
            else:
                subfolder_full = subfolder_name
            subfolder_name = os.path.basename(os.path.normpath(subfolder_name))

            if not os.path.isfile(str(subfolder_full)):
                subfolder_full_meta = (subfolder_full /
                                       DEFAULT_FILE_NAMES['filepara'])
            else:
                subfolder_full_meta = subfolder_full

            if subfolder_full_meta.exists():
                ext = load(subfolder_full, include_core=include_core)
                setattr(io, clean(subfolder_name), ext)
                io.meta._add_fileio("Added satellite account "
                                    "from {}".format(subfolder_full))
            else:
                continue

    return io

Response: Loads a full IO system with all extension in path.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def load(path, include_core=True, path_in_arc=''):
    path = Path(path)

    if not path.exists():
        raise ReadError('Given path does not exist')

    file_para = get_file_para(path=path, path_in_arc=path_in_arc)

    if file_para.content['systemtype'] == GENERIC_NAMES['iosys']:
        if zipfile.is_zipfile(str(path)):
            ret_system = IOSystem(meta=MRIOMetaData(
                location=path,
                path_in_arc=os.path.join(file_para.folder,
                                         DEFAULT_FILE_NAMES['metadata'])))
            ret_system.meta._add_fileio(
                "Loaded IO system from {} - {}".format(path, path_in_arc))
        else:
            ret_system = IOSystem(meta=MRIOMetaData(
                location=path / DEFAULT_FILE_NAMES['metadata']))
            ret_system.meta._add_fileio(
                "Loaded IO system from {}".format(path))

    elif file_para.content['systemtype'] == GENERIC_NAMES['ext']:
        ret_system = Extension(file_para.content['name'])

    else:
        raise ReadError('Type of system no defined in the file parameters')
        return None

    for key in file_para.content['files']:
        if not include_core and key not in ['A', 'L', 'Z']:
                continue

        file_name = file_para.content['files'][key]['name']
        nr_index_col = file_para.content['files'][key]['nr_index_col']
        nr_header = file_para.content['files'][key]['nr_header']
        _index_col = list(range(int(nr_index_col)))
        _header = list(range(int(nr_header)))
        _index_col = 0 if _index_col == [0] else _index_col
        _header = 0 if _header == [0] else _header

        if zipfile.is_zipfile(str(path)):
            full_file_name = os.path.join(file_para.folder, file_name)
            logging.info('Load data from {}'.format(full_file_name))

            with zipfile.ZipFile(file=str(path)) as zf:
                if (os.path.splitext(str(full_file_name))[1] == '.pkl' or
                        os.path.splitext(str(full_file_name))[1] == '.pickle'):
                    setattr(ret_system, key,
                            pd.read_pickle(zf.open(full_file_name)))
                else:
                    setattr(ret_system, key,
                            pd.read_table(zf.open(full_file_name),
                                          index_col=_index_col,
                                          header=_header))
        else:
            full_file_name = path / file_name
            logging.info('Load data from {}'.format(full_file_name))

            if (os.path.splitext(str(full_file_name))[1] == '.pkl' or
                    os.path.splitext(str(full_file_name))[1] == '.pickle'):
                setattr(ret_system, key,
                        pd.read_pickle(full_file_name))
            else:
                setattr(ret_system, key,
                        pd.read_table(full_file_name,
                                      index_col=_index_col,
                                      header=_header))
    return ret_system

Response: Loads a specific IOSystem or Extension from a JSON file.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def archive(source, archive, path_in_arc=None, remove_source=False,
            compression=zipfile.ZIP_DEFLATED, compresslevel=-1):
    """Archives a MRIO database as zip file

    This function is a wrapper around zipfile.write,
    to ease the writing of an archive and removing the source data.

    Note
    ----
    In contrast to zipfile.write, this function raises an
    error if the data (path + filename) are identical in the zip archive.
    Background: the zip standard allows that files with the same name and path
    are stored side by side in a zip file. This becomes an issue when unpacking
    this files as they overwrite each other upon extraction.

    Parameters
    ----------

    source: str or pathlib.Path or list of these
        Location of the mrio data (folder).
        If not all data should be archived, pass a list of
        all files which should be included in the archive (absolute path)

    archive: str or pathlib.Path
        Full path with filename for the archive.

    path_in_arc: string, optional
        Path within the archive zip file where data should be stored.
        'path_in_arc' must be given without leading dot and slash.
        Thus to point to the data in the root of the compressed file pass '',
        for data in e.g. the folder 'mrio_v1' pass 'mrio_v1/'.
        If None (default) data will be stored in the root of the archive.

    remove_source: boolean, optional
        If True, deletes the source file from the disk (all files
        specified in 'source' or the specified directory, depending if a
        list of files or directory was passed). If False, leaves the
        original files on disk. Also removes all empty directories
        in source including source.

    compression: ZIP compression method, optional
        This is passed to zipfile.write. By default it is set to ZIP_DEFLATED.
        NB: This is different from the zipfile default (ZIP_STORED) which would
        not give any compression. See
        https://docs.python.org/3/library/zipfile.html#zipfile-objects for
        further information. Depending on the value given here additional
        modules might be necessary (e.g. zlib for ZIP_DEFLATED). Futher
        information on this can also be found in the zipfile python docs.

    compresslevel: int, optional
        This is passed to zipfile.write and specifies the compression level.
        Acceptable values depend on the method specified at the parameter
        'compression'.  By default, it is set to -1 which gives a compromise
        between speed and size for the ZIP_DEFLATED compression (this is
        internally interpreted as 6 as described here:
        https://docs.python.org/3/library/zlib.html#zlib.compressobj )
        NB: This is only used if python version >= 3.7

    Raises
    ------
    FileExistsError: In case a file to be archived already present in the
    archive.

    """
    archive = Path(archive)

    if type(source) is not list:
        source_root = str(source)
        source_files = [f for f in Path(source).glob('**/*') if f.is_file()]
    else:
        source_root = os.path.commonpath([str(f) for f in source])
        source_files = [Path(f) for f in source]

    path_in_arc = '' if not path_in_arc else path_in_arc

    arc_file_names = {
        str(f): os.path.join(path_in_arc, str(f.relative_to(source_root)))
        for f in source_files}

    if archive.exists():
        with zipfile.ZipFile(file=str(archive), mode='r') as zf:
            already_present = zf.namelist()
        duplicates = {ff: zf for ff, zf in arc_file_names.items()
                      if zf in already_present}

        if duplicates:
            raise FileExistsError(
                'These files already exists in {arc} for '
                'path_in_arc "{pa}":\n  {filelist}'.format(
                    pa=path_in_arc, arc=archive,
                    filelist='\n  '.join(duplicates.values())))

    if sys.version_info.major == 3 and sys.version_info.minor >= 7:
        zip_open_para = dict(file=str(archive), mode='a',
                             compression=compression,
                             compresslevel=compresslevel)
    else:
        zip_open_para = dict(file=str(archive), mode='a',
                             compression=compression)

    with zipfile.ZipFile(**zip_open_para) as zz:
        for fullpath, zippath in arc_file_names.items():
            zz.write(str(fullpath), str(zippath))

    if remove_source:
        for f in source_files:
            os.remove(str(f))

        for root, dirs, files in os.walk(source_root, topdown=False):
            for name in dirs:
                dir_path = os.path.join(root, name)
                if not os.listdir(dir_path):
                    os.rmdir(os.path.join(root, name))
        try:
            os.rmdir(source_root)
        except OSError:
            pass

Response: Archives a MRIO database as a zip file.