Instruction:
Can you tell what is the following Python 3 function doing
def get_items_at_point(self, pos, selected=True, distance=0):
        items = self._qtree.find_intersect((pos[0] - distance, pos[1] - distance, 2 * distance, 2 * distance))
        filtered_items = []
        for item in self._canvas.sort(items, reverse=True):
            if not selected and item in self.selected_items:
                continue  # skip selected items

            v2i = self.get_matrix_v2i(item)
            i2v = self.get_matrix_i2v(item)
            ix, iy = v2i.transform_point(*pos)
            distance_i = item.point((ix, iy))
            distance_v = i2v.transform_distance(distance_i, 0)[0]
            if distance_v <= distance:
                filtered_items.append(item)
        return filtered_items

Response: Return the items located at the given point.


Instruction:
Write a Python 3 function that can
select an item. This adds items to the set of selected items.

Response:
def select_item(self, items):
        """ Select an items. This adds `items` to the set of selected items. """
        if not items:
            return
        elif not hasattr(items, "__iter__"):
            items = (items,)
        selection_changed = False
        with self._suppress_selection_events():
            for item in items:
                self.queue_draw_item(item)
                if item is not None and item.model not in self._selection:
                    self._selection.add(item.model)
                    selection_changed = True
        if selection_changed:
            self.emit('selection-changed', self._get_selected_items())


Instruction:
Create a Python 3 function to
clear the selected_item also clears the focused_item.

Response:
def unselect_all(self):
        """ Clearing the selected_item also clears the focused_item. """
        items = self._get_selected_items()
        with self._suppress_selection_events():
            self._selection.clear()
        self.queue_draw_item(*items)
        self.emit('selection-changed', self._get_selected_items())


Instruction:
Write a Python 3 function for
returning a set of items for each model in the current selection

Response:
def _get_selected_items(self):
        """ Return an Item (e.g. StateView) for each model (e.g. StateModel) in the current selection """
        return set(self.canvas.get_view_for_model(model) for model in self._selection)


Instruction:
Create a Python 3 function to
determine the selection The selection is based on the previous selection, the currently pressed keys and the passes newly selected items :param items: The newly selected item(s)

Response:
def handle_new_selection(self, items):
        """ Determines the selection

        The selection is based on the previous selection, the currently pressed keys and the passes newly selected items

        :param items: The newly selected item(s)
        """
        if items is None:
            items = ()
        elif not hasattr(items, "__iter__"):
            items = (items,)
        models = set(item.model for item in items)
        self._selection.handle_new_selection(models)


Instruction:
Given the following Python 3 function, write the documentation
def _get_focused_item(self):
        focused_model = self._selection.focus
        if not focused_model:
            return None
        return self.canvas.get_view_for_model(focused_model)

Response: Returns the currently focused item


Instruction:
Here you have a function in Python 3, explain what it does
def _set_focused_item(self, item):
        if not item:
            return self._del_focused_item()

        if item.model is not self._selection.focus:
            self.queue_draw_item(self._focused_item, item)
            self._selection.focus = item.model
            self.emit('focus-changed', item)

Response: Sets the focus to the passed item


Instruction:
Can you tell what is the following Python 3 function doing
def log_to_raw_structure(execution_history_items):
    previous = {}
    next_ = {}
    concurrent = {}
    grouped_by_run_id = {}
    start_item = None

    for k,v in execution_history_items.items():
        if v['item_type'] == 'StateMachineStartItem':
            start_item = v
        else:
            # connect the item to its predecessor
            prev_item_id = native_str(v['prev_history_item_id'])

            if prev_item_id in execution_history_items:
                ## should always be the case except if shelve is broken/missing data

                previous[k] = prev_item_id
                if execution_history_items[prev_item_id]['item_type'] == 'ConcurrencyItem' and \
                   execution_history_items[k]['item_type'] != 'ReturnItem':
                    # this is not a return  item, thus this 'previous' relationship of this
                    # item must be a call item of one of the concurrent branches of
                    # the concurrency state
                    if prev_item_id in concurrent:
                        concurrent[prev_item_id].append(k)
                    else:
                        concurrent[prev_item_id] = [k]
                else:
                    # this is a logical 'next' relationship
                    next_[prev_item_id] = k
            else:
                logger.warning('HistoryItem is referring to a non-existing previous history item, HistoryItem was %s' % str(v))

        rid = v['run_id']
        if rid in grouped_by_run_id:
            grouped_by_run_id[rid].append(v)
        else:
            grouped_by_run_id[rid] = [v]

    return start_item, previous, next_, concurrent, grouped_by_run_id

Response:
converts the history items in the simplest case
    to the raw structure of the log file


Instruction:
Write a Python 3 function for
collapsing structure means that all history items belonging to the same state execution are merged together into one object (e.g. CallItem and ReturnItem of an ExecutionState). This is based on the log structure in which all Items which belong together have the same run_id. The collapsed items hold input as well as output data (direct and scoped), and the outcome the state execution. :param dict execution_history_items: history items, in the simplest case directly the opened shelve log file :param bool throw_on_pickle_error: flag if an error is thrown if an object cannot be un-pickled :param bool include_erroneous_data_ports: flag if to include erroneous data ports :param bool full_next: flag to indicate if the next relationship has also to be created at the end of container states :return: start_item, the StateMachineStartItem of the log file next_, a dict mapping run_id --> run_id of the next executed state on the same hierarchy level concurrent, a dict mapping run_id --> []list of run_ids of the concurrent next executed states (if present) hierarchy, a dict mapping run_id --> run_id of the next executed state on the deeper hierarchy level (the start state within that HierarchyState) items, a dict mapping run_id --> collapsed representation of the execution of the state with that run_id :rtype: tuple

Response:
def log_to_collapsed_structure(execution_history_items, throw_on_pickle_error=True,
                               include_erroneous_data_ports=False, full_next=False):
    """
    Collapsed structure means that all history items belonging to the same state execution are
    merged together into one object (e.g. CallItem and ReturnItem of an ExecutionState). This
    is based on the log structure in which all Items which belong together have the same run_id.
    The collapsed items hold input as well as output data (direct and scoped), and the outcome
    the state execution.
    :param dict execution_history_items: history items, in the simplest case
           directly the opened shelve log file
    :param bool throw_on_pickle_error: flag if an error is thrown if an object cannot be un-pickled
    :param bool include_erroneous_data_ports: flag if to include erroneous data ports
    :param bool full_next: flag to indicate if the next relationship has also to be created at the end
           of container states
    :return: start_item, the StateMachineStartItem of the log file
             next_, a dict mapping run_id --> run_id of the next executed state on the same
                    hierarchy level
             concurrent, a dict mapping run_id --> []list of run_ids of the concurrent next
                         executed states (if present)
             hierarchy, a dict mapping run_id --> run_id of the next executed state on the
                        deeper hierarchy level (the start state within that HierarchyState)
             items, a dict mapping run_id --> collapsed representation of the execution of
                    the state with that run_id
    :rtype: tuple
    """

    # for debugging purposes
    # execution_history_items_dict = dict()
    # for k, v in execution_history_items.items():
    #     execution_history_items_dict[k] = v

    start_item, previous, next_, concurrent, grouped = log_to_raw_structure(execution_history_items)

    start_item = None
    collapsed_next = {}
    collapsed_concurrent ={}
    collapsed_hierarchy = {}
    collapsed_items = {}

    # single state executions are not supported
    if len(next_) == 0 or len(next_) == 1:
        for rid, gitems in grouped.items():
            if gitems[0]['item_type'] == 'StateMachineStartItem':
                item = gitems[0]
                execution_item = {}
                ## add base properties will throw if not existing
                for l in ['description', 'path_by_name', 'state_name', 'run_id', 'state_type',
                          'path', 'timestamp', 'root_state_storage_id', 'state_machine_version',
                          'used_rafcon_version', 'creation_time', 'last_update', 'os_environment']:
                    try:
                        execution_item[l] = item[l]
                    except KeyError:
                        logger.warning("Key {} not in history start item".format(str(l)))

                ## add extended properties (added in later rafcon versions),
                ## will add default value if not existing instead
                for l, default in [('semantic_data', {}),
                                     ('is_library', None),
                                     ('library_state_name', None),
                                     ('library_name', None),
                                     ('library_path', None)]:
                    execution_item[l] = item.get(l, default)

                start_item = execution_item
        return start_item, collapsed_next, collapsed_concurrent, collapsed_hierarchy, collapsed_items

    # build collapsed items
    for rid, gitems in grouped.items():
        if gitems[0]['item_type'] == 'StateMachineStartItem':
            item = gitems[0]
            execution_item = {}
            ## add base properties will throw if not existing
            for l in ['description', 'path_by_name', 'state_name', 'run_id', 'state_type',
                      'path', 'timestamp', 'root_state_storage_id', 'state_machine_version',
                      'used_rafcon_version', 'creation_time', 'last_update', 'os_environment']:
                try:
                    execution_item[l] = item[l]
                except KeyError:
                    logger.warning("Key {} not in history start item".format(str(l)))

            ## add extended properties (added in later rafcon versions),
            ## will add default value if not existing instead
            for l, default in [('semantic_data', {}),
                                 ('is_library', None),
                                 ('library_state_name', None),
                                 ('library_name', None),
                                 ('library_path', None)]:
                execution_item[l] = item.get(l, default)

            start_item = execution_item

            collapsed_next[rid] = execution_history_items[next_[gitems[0]['history_item_id']]]['run_id']
            collapsed_items[rid] = execution_item
        elif gitems[0]['state_type'] == 'ExecutionState' or \
             gitems[0]['state_type'] == 'HierarchyState' or \
             gitems[0]['state_type'] == 'LibraryState' or \
             'Concurrency' in gitems[0]['state_type']:

            # for item in gitems:
            #     if item["description"] is not None:
            #         print(item["item_type"], item["call_type"], item["state_type"], item["state_name"])
            #     print(item["description"])

            # select call and return items for this state
            try:
                call_item = gitems[[gitems[i]['item_type'] == 'CallItem' and \
                                    gitems[i]['call_type'] == 'EXECUTE' \
                                    for i in range(len(gitems))].index(True)]
            except ValueError:
                # fall back to container call, should only happen for root state
                try:
                    call_item = gitems[[gitems[i]['item_type'] == 'CallItem' and \
                                        gitems[i]['call_type'] == 'CONTAINER' \
                                        for i in range(len(gitems))].index(True)]
                except ValueError:
                    logger.warning('Could not find a CallItem in run_id group %s\nThere will probably be log information missing on this execution branch!' % str(rid))
                    ## create dummy returnitem with the properties referenced later in this code
                    call_item = dict(description=None,
                                     history_item_id=None,
                                     path_by_name=None,
                                     state_name=None,
                                     run_id=None,
                                     state_type=None,
                                     path=None,
                                     timestamp=None,
                                     input_output_data={},
                                     scoped_data={})

            try:
                return_item = gitems[[gitems[i]['item_type'] == 'ReturnItem' and \
                                      gitems[i]['call_type'] == 'EXECUTE' \
                                      for i in range(len(gitems))].index(True)]
            except ValueError:
                # fall back to container call, should only happen for root state
                try:
                    return_item = gitems[[gitems[i]['item_type'] == 'ReturnItem' and \
                                          gitems[i]['call_type'] == 'CONTAINER' \
                                          for i in range(len(gitems))].index(True)]
                except ValueError:
                    logger.warning('Could not find a ReturnItem in run_id group %s\nThere will probably be log information missing on this execution branch!' % str(rid))
                    ## create dummy returnitem with the properties referenced later in this code
                    return_item = dict(history_item_id=None,
                                       outcome_name=None,
                                       outcome_id=None,
                                       timestamp=None,
                                       input_output_data={},
                                       scoped_data={})

            # next item (on same hierarchy level) is always after return item
            if return_item['history_item_id'] in next_:
                # no next relationship at the end of containers
                if execution_history_items[next_[return_item['history_item_id']]]['state_type'] == 'HierarchyState' and execution_history_items[next_[return_item['history_item_id']]]['item_type'] == 'ReturnItem' and execution_history_items[next_[return_item['history_item_id']]]['call_type'] == 'CONTAINER':
                    if full_next:
                        collapsed_next[rid] = execution_history_items[next_[return_item['history_item_id']]]['run_id']
                    else:
                        pass
                else:
                    collapsed_next[rid] = execution_history_items[next_[return_item['history_item_id']]]['run_id']

            # treat hierarchy level
            if call_item['history_item_id'] in previous:
                if execution_history_items[previous[call_item['history_item_id']]]['state_type'] == 'HierarchyState' and execution_history_items[previous[call_item['history_item_id']]]['item_type'] == 'CallItem':
                    prev_rid = execution_history_items[previous[call_item['history_item_id']]]['run_id']
                    collapsed_hierarchy[prev_rid] = rid

                # treat concurrency level
                if execution_history_items[previous[call_item['history_item_id']]]['item_type'] == 'ConcurrencyItem':
                    prev_rid = execution_history_items[previous[call_item['history_item_id']]]['run_id']
                    if prev_rid in collapsed_concurrent:
                        collapsed_concurrent[prev_rid].append(rid)
                    else:
                        collapsed_concurrent[prev_rid] = [rid]

            # assemble grouped item
            execution_item = {}
            ## add base properties will throw if not existing
            for l in ['description', 'path_by_name', 'state_name', 'run_id', 'state_type', 'path']:
                execution_item[l] = call_item[l]

            ## add extended properties (added in later rafcon versions),
            ## will add default value if not existing instead
            for l, default in [('semantic_data', {}),
                                 ('is_library', None),
                                 ('library_state_name', None),
                                 ('library_name', None),
                                 ('library_path', None)]:
                execution_item[l] = return_item.get(l, default)

            for l in ['outcome_name', 'outcome_id']:
                execution_item[l] = return_item[l]
            for l in ['timestamp']:
                execution_item[l+'_call'] = call_item[l]
                execution_item[l+'_return'] = return_item[l]

            def unpickle_data(data_dict):
                r = dict()
                # support backward compatibility
                if isinstance(data_dict, string_types):  # formerly data dict was a json string
                    r = json.loads(data_dict)
                else:
                    for k, v in data_dict.items():
                        if not k.startswith('!'): # ! indicates storage error
                            try:
                                r[k] = pickle.loads(v)
                            except Exception as e:
                                if throw_on_pickle_error:
                                    raise
                                elif include_erroneous_data_ports:
                                    r['!' + k] = (str(e), v)
                                else:
                                    pass # ignore
                        elif include_erroneous_data_ports:
                            r[k] = v

                return r

            execution_item['data_ins'] = unpickle_data(call_item['input_output_data'])
            execution_item['data_outs'] = unpickle_data(return_item['input_output_data'])
            execution_item['scoped_data_ins'] = unpickle_data(call_item['scoped_data'])
            execution_item['scoped_data_outs'] = unpickle_data(return_item['scoped_data'])
            execution_item['semantic_data'] = unpickle_data(execution_item['semantic_data'])

            collapsed_items[rid] = execution_item

    return start_item, collapsed_next, collapsed_concurrent, collapsed_hierarchy, collapsed_items


Instruction:
Can you create a Python 3 function that
returns a pandas. DataFrame containing all the data flow items in the execution history.

Response:
def log_to_DataFrame(execution_history_items, data_in_columns=[], data_out_columns=[], scoped_in_columns=[],
                     scoped_out_columns=[], semantic_data_columns=[], throw_on_pickle_error=True):
    """
    Returns all collapsed items in a table-like structure (pandas.DataFrame) with one row per executed
    state and a set of properties resp. columns (e.g. state_name, outcome, run_id) for this state.
    The data flow (data_in/out, scoped_data_in/out, semantic_data) is omitted from this table
    representation by default, as the different states have different data in-/out-port, scoped_data-
    ports and semantic_data defined. However, you can ask specific data-/scoped_data-ports and semantic
    data to be exported as table column, given they are primitive-valued, by including the port / key
    names in the *_selected-parameters. These table-columns will obviously only be well-defined for
    states having this kind of port-name-/semantic-key and otherwise will contain a None-like value,
    indicating missing data.

    The available data per execution item (row in the table) can be printed using pandas.DataFrame.columns.
    """
    try:
        import pandas as pd
    except ImportError:
        raise ImportError("The Python package 'pandas' is required for log_to_DataFrame.")

    start, next_, concurrency, hierarchy, gitems = log_to_collapsed_structure(
        execution_history_items, throw_on_pickle_error=throw_on_pickle_error)
    gitems.pop(start['run_id'])
    if len(gitems) == 0:
        return pd.DataFrame()

    # remove columns which are not generic over all states (basically the
    # data flow stuff)
    df_keys = list(list(gitems.values())[0].keys())
    df_keys.remove('data_ins')
    df_keys.remove('data_outs')
    df_keys.remove('scoped_data_ins')
    df_keys.remove('scoped_data_outs')
    df_keys.remove('semantic_data')
    df_keys.sort()

    df_items = []

    for rid, item in gitems.items():
        row_data = [item[k] for k in df_keys]

        for key, selected_columns in [('data_ins', data_in_columns),
                                      ('data_outs', data_out_columns),
                                      ('scoped_data_ins', scoped_in_columns),
                                      ('scoped_data_outs', scoped_out_columns),
                                      ('semantic_data', semantic_data_columns)]:
            for column_key in selected_columns:
                row_data.append(item[key].get(column_key, None))
        df_items.append(row_data)

    for key, selected_columns in [('data_ins', data_in_columns),
                                  ('data_outs', data_out_columns),
                                  ('scoped_data_ins', scoped_in_columns),
                                  ('scoped_data_outs', scoped_out_columns),
                                  ('semantic_data', semantic_data_columns)]:
        df_keys.extend([key + '__' + s for s in selected_columns])
    df = pd.DataFrame(df_items, columns=df_keys)
    # convert epoch to datetime
    df.timestamp_call = pd.to_datetime(df.timestamp_call, unit='s')
    df.timestamp_return = pd.to_datetime(df.timestamp_return, unit='s')

    # use call timestamp as index
    df_timed = df.set_index(df.timestamp_call)
    df_timed.sort_index(inplace=True)

    return df_timed


Instruction:
How would you explain what the following Python 3 function does
def log_to_ganttplot(execution_history_items):
    import matplotlib.pyplot as plt
    import matplotlib.dates as dates
    import numpy as np

    d = log_to_DataFrame(execution_history_items)

    # de-duplicate states and make mapping from state to idx
    unique_states, idx = np.unique(d.path_by_name, return_index=True)
    ordered_unique_states = np.array(d.path_by_name)[np.sort(idx)]
    name2idx = {k: i for i, k in enumerate(ordered_unique_states)}

    calldate = dates.date2num(d.timestamp_call.dt.to_pydatetime())
    returndate = dates.date2num(d.timestamp_return.dt.to_pydatetime())

    state2color = {'HierarchyState': 'k',
                   'ExecutionState': 'g',
                   'BarrierConcurrencyState': 'y',
                   'PreemptiveConcurrencyState': 'y'}

    fig, ax = plt.subplots(1, 1)
    ax.barh(bottom=[name2idx[k] for k in d.path_by_name], width=returndate-calldate,
            left=calldate, align='center', color=[state2color[s] for s in d.state_type], lw=0.0)
    plt.yticks(list(range(len(ordered_unique_states))), ordered_unique_states)

Response: Example how to use the DataFrame representation


Instruction:
Implement a Python 3 function for
wrapping method for GLib. idle_add

Response:
def call_gui_callback(callback, *args, **kwargs):
    """Wrapper method for GLib.idle_add

    This method is intended as replacement for idle_add. It wraps the method with a callback option. The advantage is
    that this way, the call is blocking. The method return, when the callback method has been called and executed.

    :param callback: The callback method, e.g. on_open_activate
    :param args: The parameters to be passed to the callback method
    """
    from future.utils import raise_
    from threading import Condition
    import sys
    from rafcon.utils import log
    global exception_info, result
    from gi.repository import GLib
    condition = Condition()
    exception_info = None

    @log.log_exceptions()
    def fun():
        """Call callback and notify condition variable
        """
        global exception_info, result
        result = None
        try:
            result = callback(*args)
        except:
            # Exception within this asynchronously called function won't reach pytest. This is why we have to store
            # the information about the exception to re-raise it at the end of the synchronous call.
            exception_info = sys.exc_info()
        finally:  # Finally is also executed in the case of exceptions
            condition.acquire()
            condition.notify()
            condition.release()

    if "priority" in kwargs:
        priority = kwargs["priority"]
    else:
        priority = GLib.PRIORITY_LOW

    condition.acquire()
    GLib.idle_add(fun, priority=priority)
    # Wait for the condition to be notified
    # TODO: implement timeout that raises an exception
    condition.wait()
    condition.release()
    if exception_info:
        e_type, e_value, e_traceback = exception_info
        raise_(e_type, e_value, e_traceback)
    return result


Instruction:
Explain what the following Python 3 code does
def create_tab_header_label(tab_name, icons):
    tooltip_event_box = Gtk.EventBox()
    tooltip_event_box.set_tooltip_text(tab_name)
    tab_label = Gtk.Label()
    if global_gui_config.get_config_value('USE_ICONS_AS_TAB_LABELS', True):
        tab_label.set_markup('<span font_desc="%s %s">&#x%s;</span>' %
                            (constants.ICON_FONT,
                            constants.FONT_SIZE_BIG,
                            icons[tab_name]))
    else:
        tab_label.set_text(get_widget_title(tab_name))
        tab_label.set_angle(90)
    tab_label.show()
    tooltip_event_box.add(tab_label)
    tooltip_event_box.set_visible_window(False)
    tooltip_event_box.show()
    return tooltip_event_box

Response: Create the tab header label for notebook tabs.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def create_button_label(icon, font_size=constants.FONT_SIZE_NORMAL):
    label = Gtk.Label()
    set_label_markup(label, '&#x' + icon + ';', constants.ICON_FONT, font_size)
    label.show()
    return label

Response: Create a button label with a chosen icon.


Instruction:
Can you write a function in Python 3 where it
transforms Notebook tab label to title by replacing underscores with white spaces and capitalizing the first letter of each word.

Response:
def get_widget_title(tab_label_text):
    """Transform Notebook tab label to title by replacing underscores with white spaces and capitalizing the first
    letter of each word.

    :param tab_label_text: The string of the tab label to be transformed
    :return: The transformed title as a string
    """
    title = ''
    title_list = tab_label_text.split('_')
    for word in title_list:
        title += word.upper() + ' '
    title.strip()
    return title


Instruction:
Can you generate a brief explanation for the following Python 3 code
def set_notebook_title(notebook, page_num, title_label):
    text = get_notebook_tab_title(notebook, page_num)
    set_label_markup(title_label, text, constants.INTERFACE_FONT, constants.FONT_SIZE_BIG, constants.LETTER_SPACING_1PT)
    return text

Response: Set the title of a GTK notebook to one of its tab s titles.


Instruction:
How would you explain what the following Python 3 function does
def create_menu_box_with_icon_and_label(label_text):
    box = Gtk.Box.new(Gtk.Orientation.HORIZONTAL, 10)
    box.set_border_width(0)
    icon_label = Gtk.Label()
    text_label = Gtk.AccelLabel.new(label_text)
    text_label.set_xalign(0)

    box.pack_start(icon_label, False, False, 0)
    box.pack_start(text_label, True, True, 0)
    return box, icon_label, text_label

Response: Creates a MenuItem box with icon and label.


Instruction:
Given the following Python 3 function, write the documentation
def set_window_size_and_position(window, window_key):
    size = global_runtime_config.get_config_value(window_key + '_WINDOW_SIZE')
    position = global_runtime_config.get_config_value(window_key + '_WINDOW_POS')
    maximized = global_runtime_config.get_config_value(window_key + '_WINDOW_MAXIMIZED')

    # un-maximize here on purpose otherwise resize and reposition fails
    if not maximized:
        window.unmaximize()

    if not size:
        size = constants.WINDOW_SIZE[window_key + '_WINDOW']
    window.resize(*size)
    if position:
        position = (max(0, position[0]), max(0, position[1]))
        screen_width = Gdk.Screen.width()
        screen_height = Gdk.Screen.height()
        if position[0] < screen_width and position[1] < screen_height:
            window.move(*position)
    else:
        window.set_position(Gtk.WindowPosition.MOUSE)
    if maximized:
        window.maximize()
    window.show()

Response: Adjust GTK Window s size and position according to the corresponding values in the runtime_config file.


Instruction:
Write a Python 3 script to
check whether the widget is supposed to react to the event.

Response:
def react_to_event(view, widget, event):
    """Checks whether the widget is supposed to react to passed event

    The function is intended for callback methods registering to shortcut actions. As several widgets can register to
    the same shortcut, only the one having the focus should react to it.

    :param gtkmvc3.View view: The view in which the widget is registered
    :param Gtk.Widget widget: The widget that subscribed to the shortcut action, should be the top widget of the view
    :param event: The event that caused the callback
    :return: Whether the widget is supposed to react to the event or not
    :rtype: bool
    """
    # See
    # http://pyGtk.org/pygtk2reference/class-gtkwidget.html#method-gtkwidget--is-focus and
    # http://pyGtk.org/pygtk2reference/class-gtkwidget.html#method-gtkwidget--has-focus
    # for detailed information about the difference between is_focus() and has_focus()
    if not view:  # view needs to be initialized
        return False
    # widget parameter must be set and a Gtk.Widget
    if not isinstance(widget, Gtk.Widget):
        return False
    # Either the widget itself or one of its children must be the focus widget within their toplevel
    child_is_focus = False if not isinstance(widget, Gtk.Container) else bool(widget.get_focus_child())
    if not child_is_focus and not widget.is_focus():
        return False

    def has_focus(widget):
        """Checks whether `widget` or one of its children ``has_focus()`` is ``True``

        :param Gtk.Widget widget: The widget to be checked
        :return: If any (child) widget has the global input focus
        """
        if widget.has_focus():
            return True
        if not isinstance(widget, Gtk.Container):
            return False
        return any(has_focus(child) for child in widget.get_children())
    # Either, for any of widget or its children, has_focus must be True, in this case the widget has the global focus.
    if has_focus(widget):
        return True
    # Or the callback was not triggered by a shortcut, but e.g. a mouse click or a call from a test.
    # If the callback was triggered by a shortcut action, the event has at least a length of two and the second
    # element is a Gdk.ModifierType
    if len(event) < 2 or (len(event) >= 2 and not isinstance(event[1], Gdk.ModifierType)):
        return True
    return False


Instruction:
Write a Python 3 function for
checking if the event is of right type

Response:
def is_event_of_key_string(event, key_string):
    """Condition check if key string represent the key value of handed event and whether the event is of right type

    The function checks for constructed event tuple that are generated by the rafcon.gui.shortcut_manager.ShortcutManager.
    :param tuple event: Event tuple generated by the ShortcutManager
    :param str key_string: Key string parsed to a key value and for condition check
    """
    return len(event) >= 2 and not isinstance(event[1], Gdk.ModifierType) and event[0] == Gtk.accelerator_parse(key_string)[0]


Instruction:
Can you create a Python 3 function that
calls when the View was registered

Response:
def register_view(self, view):
        """Called when the View was registered"""
        super(TopToolBarController, self).register_view(view)
        view['maximize_button'].connect('clicked', self.on_maximize_button_clicked)
        self.update_maximize_button()


Instruction:
Can you write a function in Python 3 where it
calls when the View was registered

Response:
def register_view(self, view):
        """Called when the View was registered"""
        super(TopToolBarUndockedWindowController, self).register_view(view)
        view['redock_button'].connect('clicked', self.on_redock_button_clicked)


Instruction:
Make a summary of the following Python 3 code
def register_view(self, view):
        super(SingleWidgetWindowController, self).register_view(view)
        self.shortcut_manager = ShortcutManager(self.view['main_window'])
        self.register_actions(self.shortcut_manager)

        view['main_window'].connect('destroy', Gtk.main_quit)

Response: Called when the View was registered


Instruction:
Can you generate a brief explanation for the following Python 3 code
def remove_outcome(self, outcome_id, force=False, destroy=True):
        if force:
            return State.remove_outcome(self, outcome_id, force, destroy)
        else:
            raise NotImplementedError("Remove outcome is not implemented for library state {}".format(self))

Response: Overwrites the remove_outcome method of the State class. Removes the outcome from the library state.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def remove_output_data_port(self, data_port_id, force=False, destroy=True):
        if force:
            return State.remove_output_data_port(self, data_port_id, force, destroy)
        else:
            raise NotImplementedError("Remove output data port is not implemented for library state {}".format(self))

Response: Overwrites the remove_output_data_port method of the State class to allow the user to remove an output data port from the library state.


Instruction:
How would you code a function in Python 3 to
calculate the library hierarchy depth of the current library state.

Response:
def library_hierarchy_depth(self):
        """ Calculates the library hierarchy depth

        Counting starts at the current library state. So if the there is no upper library state the depth is one.

        :return: library hierarchy depth
        :rtype: int
        """
        current_library_hierarchy_depth = 1
        library_root_state = self.get_next_upper_library_root_state()
        while library_root_state is not None:
            current_library_hierarchy_depth += 1
            library_root_state = library_root_state.parent.get_next_upper_library_root_state()
        return current_library_hierarchy_depth


Instruction:
Here you have a function in Python 3, explain what it does
def load(self, config_file=None, path=None):
        if config_file is None:
            if path is None:
                path, config_file = split(resource_filename(__name__, CONFIG_FILE))
            else:
                config_file = CONFIG_FILE
        super(Config, self).load(config_file, path)

Response: Loads the configuration from a specific file


Instruction:
Implement a function in Python 3 to
call when the view was registered

Response:
def register_view(self, view):
        """Called when the View was registered

        Can be used e.g. to connect signals. Here, the destroy signal is connected to close the application
        """
        super(StateEditorController, self).register_view(view)
        view.prepare_the_labels()  # the preparation of the labels is done here to take into account plugin hook changes
        view['add_input_port_button'].connect('clicked', self.inputs_ctrl.on_add)
        view['add_output_port_button'].connect('clicked', self.outputs_ctrl.on_add)
        if isinstance(self.model, ContainerStateModel):
            view['add_scoped_variable_button'].connect('clicked', self.scopes_ctrl.on_add)

        view['remove_input_port_button'].connect('clicked', self.inputs_ctrl.on_remove)
        view['remove_output_port_button'].connect('clicked', self.outputs_ctrl.on_remove)
        if isinstance(self.model, ContainerStateModel):
            view['remove_scoped_variable_button'].connect('clicked', self.scopes_ctrl.on_remove)

        if isinstance(self.model, LibraryStateModel) or self.model.state.get_next_upper_library_root_state():
            view['add_input_port_button'].set_sensitive(False)
            view['remove_input_port_button'].set_sensitive(False)
            view['add_output_port_button'].set_sensitive(False)
            view['remove_output_port_button'].set_sensitive(False)
            view['add_scoped_variable_button'].set_sensitive(False)
            view['remove_scoped_variable_button'].set_sensitive(False)

        view.inputs_view.show()
        view.outputs_view.show()
        view.scopes_view.show()
        view.outcomes_view.show()
        view.transitions_view.show()
        view.data_flows_view.show()

        # show scoped variables if show content is enabled -> if disabled the tab stays and indicates a container state
        if isinstance(self.model, LibraryStateModel) and not self.model.show_content():
            view.scopes_view.hide()
            view.linkage_overview.scope_view.hide()

        # Container states do not have a source editor and library states does not show there source code
        # Thus, for those states we do not have to add the source controller and can hide the source code tab
        # logger.info("init state: {0}".format(model))
        lib_with_and_ES_as_root = isinstance(self.model, LibraryStateModel) and \
                                  not isinstance(self.model.state_copy, ContainerStateModel)
        if not isinstance(self.model, ContainerStateModel) and not isinstance(self.model, LibraryStateModel) or \
                lib_with_and_ES_as_root:
            view.source_view.show()
            if isinstance(self.model, LibraryStateModel) and not self.model.show_content():
                view.remove_source_tab()
            view.remove_scoped_variables_tab()
        else:
            view.scopes_view.show()
            if isinstance(self.model, LibraryStateModel) and \
                    (not self.model.show_content() or not isinstance(self.model.state_copy, ContainerStateModel)):
                view.remove_scoped_variables_tab()
            view.remove_source_tab()

        if global_gui_config.get_config_value("SEMANTIC_DATA_MODE", False):
            view.bring_tab_to_the_top('Semantic Data')
        else:
            if isinstance(self.model.state, LibraryState):
                view.bring_tab_to_the_top('Description')
            else:
                view.bring_tab_to_the_top('Linkage Overview')

        if isinstance(self.model, ContainerStateModel):
            self.scopes_ctrl.reload_scoped_variables_list_store()

        plugins.run_hook("post_state_editor_register_view", self)


Instruction:
Here you have a function in Python 3, explain what it does
def state_type_changed(self, model, prop_name, info):
        msg = info['arg']
        # print(self.__class__.__name__, "state_type_changed check", info)
        if msg.action in ['change_state_type', 'change_root_state_type'] and msg.after:
            # print(self.__class__.__name__, "state_type_changed")
            import rafcon.gui.singleton as gui_singletons
            msg = info['arg']
            new_state_m = msg.affected_models[-1]
            states_editor_ctrl = gui_singletons.main_window_controller.get_controller('states_editor_ctrl')
            states_editor_ctrl.recreate_state_editor(self.model, new_state_m)

Response: Reopen state editor when state type is changed


Instruction:
Can you generate the documentation for the following Python 3 function
def state_destruction(self, model, prop_name, info):
        import rafcon.gui.singleton as gui_singletons
        states_editor_ctrl = gui_singletons.main_window_controller.get_controller('states_editor_ctrl')
        state_identifier = states_editor_ctrl.get_state_identifier(self.model)
        states_editor_ctrl.close_page(state_identifier, delete=True)

Response: Close state editor when state is being destructed


Instruction:
Write a Python 3 function that can
prepare the model for destruction

Response:
def prepare_destruction(self):
        """Prepares the model for destruction

        Unregister itself as observer from the state machine and the root state
        """
        if self.state_machine is None:
            logger.verbose("Multiple calls of prepare destruction for {0}".format(self))
        self.destruction_signal.emit()
        if self.history is not None:
            self.history.prepare_destruction()
        if self.auto_backup is not None:
            self.auto_backup.prepare_destruction()
        try:
            self.unregister_observer(self)
            self.root_state.unregister_observer(self)
        except KeyError:  # Might happen if the observer was already unregistered
            pass
        with self.state_machine.modification_lock():
            self.root_state.prepare_destruction()
        self.root_state = None
        self.state_machine = None
        super(StateMachineModel, self).prepare_destruction()


Instruction:
How would you implement a function in Python 3 that
calls when a state machine action was triggered.

Response:
def action_signal_triggered(self, model, prop_name, info):
        """When the action was performed, we have to set the dirty flag, as the changes are unsaved"""
        # print("ACTION_signal_triggered state machine: ", model, prop_name, info)
        self.state_machine.marked_dirty = True
        msg = info.arg
        if model is not self and msg.action.startswith('sm_notification_'):  # Signal was caused by the root state
            # Emit state_action_signal to inform observing controllers about changes made to the state within the
            # state machine
            # print("DONE1 S", self.state_machine.state_machine_id, msg, model)
            # -> removes mark of "sm_notification_"-prepend to mark root-state msg forwarded to state machine label
            msg = msg._replace(action=msg.action.replace('sm_notification_', '', 1))
            self.state_action_signal.emit(msg)
            # print("FINISH DONE1 S", self.state_machine.state_machine_id, msg)
        else:
            # print("DONE2 S", self.state_machine.state_machine_id, msg)
            pass


Instruction:
Can you implement a function in Python 3 that
returns the StateModel for the given path.

Response:
def get_state_model_by_path(self, path):
        """Returns the `StateModel` for the given `path`

        Searches a `StateModel` in the state machine, who's path is given by `path`.

        :param str path: Path of the searched state
        :return: The state with that path
        :rtype: StateModel
        :raises: ValueError, if path is invalid/not existing with this state machine
        """
        path_elements = path.split('/')
        path_elements.pop(0)
        current_state_model = self.root_state
        for state_id in path_elements:
            if isinstance(current_state_model, ContainerStateModel):
                if state_id in current_state_model.states:
                    current_state_model = current_state_model.states[state_id]
                else:
                    raise ValueError("Invalid path: State with id '{}' not found in state with id {}".format(
                        state_id, current_state_model.state.state_id))
            elif isinstance(current_state_model, LibraryStateModel):
                if state_id == current_state_model.state_copy.state.state_id:
                    current_state_model = current_state_model.state_copy
                else:
                    raise ValueError("Invalid path: state id '{}' does not coincide with state id '{}' of state_copy "
                                     "of library state with id '{}'".format(
                                        state_id, current_state_model.state_copy.state.state_id,
                                        current_state_model.state.state_id))
            else:
                raise ValueError("Invalid path: State with id '{}' has no children".format(
                    current_state_model.state.state_id))
        return current_state_model


Instruction:
Can you generate the documentation for the following Python 3 function
def load_meta_data(self, path=None, recursively=True):
        meta_data_path = path if path is not None else self.state_machine.file_system_path

        if meta_data_path:
            path_meta_data = os.path.join(meta_data_path, storage.FILE_NAME_META_DATA)

            try:
                tmp_meta = storage.load_data_file(path_meta_data)
            except ValueError:
                tmp_meta = {}
        else:
            tmp_meta = {}

        # JSON returns a dict, which must be converted to a Vividict
        tmp_meta = Vividict(tmp_meta)

        if recursively:
            root_state_path = None if not path else os.path.join(path, self.root_state.state.state_id)
            self.root_state.load_meta_data(root_state_path)

        if tmp_meta:
            # assign the meta data to the state
            self.meta = tmp_meta
            self.meta_signal.emit(MetaSignalMsg("load_meta_data", "all", True))

Response: Loads the meta data of the state machine model from the file system.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def store_meta_data(self, copy_path=None):
        if copy_path:
            meta_file_json = os.path.join(copy_path, storage.FILE_NAME_META_DATA)
        else:
            meta_file_json = os.path.join(self.state_machine.file_system_path, storage.FILE_NAME_META_DATA)

        storage_utils.write_dict_to_json(self.meta, meta_file_json)

        self.root_state.store_meta_data(copy_path)

Response: Save the meta data of the state machine model to the file system


Instruction:
Explain what the following Python 3 code does
def convert_trees(self, ptb_trees, representation='basic', universal=True,
                      include_punct=True, include_erased=False, **kwargs):
        """Convert a list of Penn Treebank formatted strings (ptb_trees)
        into Stanford Dependencies. The dependencies are represented
        as a list of sentences (CoNLL.Corpus), where each sentence
        (CoNLL.Sentence) is itself a list of CoNLL.Token objects.

        Currently supported representations are 'basic', 'collapsed',
        'CCprocessed', and 'collapsedTree' which behave the same as they
        in the CoreNLP command line tools. (note that in the online
        CoreNLP demo, 'collapsed' is called 'enhanced')

        Additional arguments: universal (if True, use universal
        dependencies if they're available), include_punct (if False,
        punctuation tokens will not be included), and include_erased
        (if False and your representation might erase tokens, those
        tokens will be omitted from the output).

        See documentation on your backend to see if it supports
        further options."""
        kwargs.update(representation=representation, universal=universal,
                      include_punct=include_punct,
                      include_erased=include_erased)
        return Corpus(self.convert_tree(ptb_tree, **kwargs)
                      for ptb_tree in ptb_trees)

Response: Convert a list of Penn Treebank formatted strings into Stanford Dependencies.


Instruction:
Make a summary of the following Python 3 code
def setup_and_get_default_path(self, jar_base_filename):
        import os
        import errno
        install_dir = os.path.expanduser(INSTALL_DIR)
        try:
            os.makedirs(install_dir)
        except OSError as ose:
            if ose.errno != errno.EEXIST:
                raise ose
        jar_filename = os.path.join(install_dir, jar_base_filename)
        return jar_filename

Response:
Setup the user - specific install path for the Stanford
        Dependencies jar if the jar_url is not specified and ensure that the directory exists and return the full path for the jar file.


Instruction:
Write a Python 3 function for
downloading the jar for version into the jar_filename specified by the constructor. Will not overwrite jar_filename if it already exists.

Response:
def download_if_missing(self, version=None, verbose=True):
        """Download the jar for version into the jar_filename specified
        in the constructor. Will not overwrite jar_filename if it already
        exists. version defaults to DEFAULT_CORENLP_VERSION (ideally the
        latest but we can't guarantee that since PyStanfordDependencies
        is distributed separately)."""
        if os.path.exists(self.jar_filename):
            return

        jar_url = self.get_jar_url(version)
        if verbose:
            print("Downloading %r -> %r" % (jar_url, self.jar_filename))
        opener = ErrorAwareURLOpener()
        opener.retrieve(jar_url, filename=self.jar_filename)


Instruction:
Can you implement a function in Python 3 that
ensures that the given representation is a known Stanford Dependency representation.

Response:
def _raise_on_bad_representation(representation):
        """Ensure that representation is a known Stanford Dependency
        representation (raises a ValueError if the representation is
        invalid)."""
        if representation not in REPRESENTATIONS:
            repr_desc = ', '.join(map(repr, REPRESENTATIONS))
            raise ValueError("Unknown representation: %r (should be one "
                             "of %s)" % (representation, repr_desc))


Instruction:
How would you implement a function in Python 3 that
ensures that jar_filename is a valid path to a jar file.

Response:
def _raise_on_bad_jar_filename(jar_filename):
        """Ensure that jar_filename is a valid path to a jar file."""
        if jar_filename is None:
            return

        if not isinstance(jar_filename, string_type):
            raise TypeError("jar_filename is not a string: %r" % jar_filename)

        if not os.path.exists(jar_filename):
            raise ValueError("jar_filename does not exist: %r" % jar_filename)


Instruction:
Create a Python 3 function for
getting the URL to a Stanford CoreNLP jar file with a specific version.

Response:
def get_jar_url(version=None):
        """Get the URL to a Stanford CoreNLP jar file with a specific
        version. These jars come from Maven since the Maven version is
        smaller than the full CoreNLP distributions. Defaults to
        DEFAULT_CORENLP_VERSION."""
        if version is None:
            version = DEFAULT_CORENLP_VERSION

        try:
            string_type = basestring
        except NameError:
            string_type = str

        if not isinstance(version, string_type):
            raise TypeError("Version must be a string or None (got %r)." %
                            version)
        jar_filename = 'stanford-corenlp-%s.jar' % version
        return 'http://search.maven.org/remotecontent?filepath=' + \
               'edu/stanford/nlp/stanford-corenlp/%s/%s' % (version,
                                                            jar_filename)


Instruction:
Can you tell what is the following Python 3 function doing
def convert_tree(self, ptb_tree, representation='basic',
                     include_punct=True, include_erased=False,
                     add_lemmas=False, universal=True):
        """Arguments are as in StanfordDependencies.convert_trees but with
        the addition of add_lemmas. If add_lemmas=True, we will run the
        Stanford CoreNLP lemmatizer and fill in the lemma field."""
        self._raise_on_bad_input(ptb_tree)
        self._raise_on_bad_representation(representation)
        tree = self.treeReader(ptb_tree)
        if tree is None:
            raise ValueError("Invalid Penn Treebank tree: %r" % ptb_tree)
        deps = self._get_deps(tree, include_punct, representation,
                              universal=universal)

        tagged_yield = self._listify(tree.taggedYield())
        indices_to_words = dict(enumerate(tagged_yield, 1))
        sentence = Sentence()
        covered_indices = set()

        def add_token(index, form, head, deprel, extra):
            tag = indices_to_words[index].tag()
            if add_lemmas:
                lemma = self.stem(form, tag)
            else:
                lemma = None
            token = Token(index=index, form=form, lemma=lemma, cpos=tag,
                          pos=tag, feats=None, head=head, deprel=deprel,
                          phead=None, pdeprel=None, extra=extra)
            sentence.append(token)

        # add token for each dependency
        for dep in deps:
            index = dep.dep().index()
            head = dep.gov().index()
            deprel = dep.reln().toString()
            form = indices_to_words[index].value()

            dep_is_copy = dep.dep().copyCount()
            gov_is_copy = dep.gov().copyCount()
            if dep_is_copy or gov_is_copy:
                extra = {}
                if dep_is_copy:
                    extra['dep_is_copy'] = dep_is_copy
                if gov_is_copy:
                    extra['gov_is_copy'] = gov_is_copy
            else:
                extra = None
            add_token(index, form, head, deprel, extra)
            covered_indices.add(index)
        if include_erased:
            # see if there are any tokens that were erased
            # and add them as well
            all_indices = set(indices_to_words.keys())
            for index in all_indices - covered_indices:
                form = indices_to_words[index].value()
                if not include_punct and not self.puncFilter(form):
                    continue
                add_token(index, form, head=0, deprel='erased', extra=None)
            # erased generally disrupt the ordering of the sentence
            sentence.sort()

        if representation == 'basic':
            sentence.renumber()
        return sentence

Response: Converts a Penn Treebank tree into a Stanford Information object.


Instruction:
How would you code a function in Python 3 to
return the stem of word with specific form and part - of - speech tag according to the Stanford lemmatizer. Lemmas are cached if necessary.

Response:
def stem(self, form, tag):
        """Returns the stem of word with specific form and part-of-speech
        tag according to the Stanford lemmatizer. Lemmas are cached."""
        key = (form, tag)
        if key not in self.lemma_cache:
            lemma = self.stemmer(*key).word()
            self.lemma_cache[key] = lemma
        return self.lemma_cache[key]


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _get_deps(self, tree, include_punct, representation, universal):
        if universal:
            converter = self.universal_converter

            if self.universal_converter == self.converter:
                import warnings
                warnings.warn("This jar doesn't support universal "
                              "dependencies, falling back to Stanford "
                              "Dependencies. To suppress this message, "
                              "call with universal=False")
        else:
            converter = self.converter

        if include_punct:
            egs = converter(tree, self.acceptFilter)
        else:
            egs = converter(tree)

        if representation == 'basic':
            deps = egs.typedDependencies()
        elif representation == 'collapsed':
            deps = egs.typedDependenciesCollapsed(True)
        elif representation == 'CCprocessed':
            deps = egs.typedDependenciesCCprocessed(True)
        else:
            # _raise_on_bad_representation should ensure that this
            # assertion doesn't fail
            assert representation == 'collapsedTree'
            deps = egs.typedDependenciesCollapsedTree()
        return self._listify(deps)

Response: Get a list of dependencies from a Stanford Tree for a specific Universal Dependencies representation.


Instruction:
Implement a Python 3 function for
representing this Token as a string in CoNLL - X format.

Response:
def as_conll(self):
        """Represent this Token as a line as a string in CoNLL-X format."""
        def get(field):
            value = getattr(self, field)
            if value is None:
                value = '_'
            elif field == 'feats':
                value = '|'.join(value)
            return str(value)
        return '\t'.join([get(field) for field in FIELD_NAMES])


Instruction:
How would you code a function in Python 3 to
construct a Token from a line in CoNLL - X format.

Response:
def from_conll(this_class, text):
        """Construct a Token from a line in CoNLL-X format."""
        fields = text.split('\t')
        fields[0] = int(fields[0]) # index
        fields[6] = int(fields[6]) # head index
        if fields[5] != '_': # feats
            fields[5] = tuple(fields[5].split('|'))
        fields = [value if value != '_' else None for value in fields]
        fields.append(None) # for extra
        return this_class(**dict(zip(FIELD_NAMES_PLUS, fields)))


Instruction:
How would you implement a function in Python 3 that
represents this Sentence as an ASCII tree string. Requires a str_func which should take a single Token and return a string.

Response:
def as_asciitree(self, str_func=None):
        """Represent this Sentence as an ASCII tree string. Requires
        the asciitree package. A default token stringifier is provided
        but for custom formatting, specify a str_func which should take
        a single Token and return a string."""
        import asciitree
        from collections import defaultdict
        children = defaultdict(list)
        # since erased nodes may be missing, multiple tokens may have same
        # index (CCprocessed), etc.
        token_to_index = {}
        roots = []
        for token in self:
            children[token.head].append(token)
            token_to_index[token] = token.index
            if token.head == 0:
                roots.append(token)
        assert roots, "Couldn't find root Token(s)"

        if len(roots) > 1:
            # multiple roots so we make a fake one to be their parent
            root = Token(0, 'ROOT', 'ROOT-LEMMA', 'ROOT-CPOS', 'ROOT-POS',
                         None, None, 'ROOT-DEPREL', None, None, None)
            token_to_index[root] = 0
            children[0] = roots
        else:
            root = roots[0]

        def child_func(token):
            index = token_to_index[token]
            return children[index]
        if not str_func:
            def str_func(token):
                return ' %s [%s]' % (token.form, token.deprel)

        return asciitree.draw_tree(root, child_func, str_func)


Instruction:
Implement a Python 3 function for
returning this sentence as a graphviz. Digraph.

Response:
def as_dotgraph(self, digraph_kwargs=None, id_prefix=None,
                    node_formatter=None, edge_formatter=None):
        """Returns this sentence as a graphviz.Digraph. Requires the
        graphviz Python package and graphviz itself. There are several
        ways to customize. Graph level keyword arguments can be passed
        as a dictionary to digraph_kwargs. If you're viewing multiple
        Sentences in the same graph, you'll need to set a unique prefix
        string in id_prefix. Lastly, you can change the formatting of
        nodes and edges with node_formatter and edge_formatter. Both
        take a single Token as an argument (for edge_formatter, the
        Token represents the child token) and return a dictionary of
        keyword arguments which are passed to the node and edge creation
        functions in graphviz. The node_formatter will also be called
        with None as its token when adding the root."""
        digraph_kwargs = digraph_kwargs or {}
        id_prefix = id_prefix or ''

        node_formatter = node_formatter or (lambda token: {})
        edge_formatter = edge_formatter or (lambda token: {})

        import graphviz
        graph = graphviz.Digraph(**digraph_kwargs)
        # add root node
        graph.node(id_prefix + '0', 'root', **node_formatter(None))

        # add remaining nodes and edges
        already_added = set()
        for token in self:
            token_id = id_prefix + str(token.index)
            parent_id = id_prefix + str(token.head)
            if token_id not in already_added:
                graph.node(token_id, token.form, **node_formatter(token))
            graph.edge(parent_id, token_id, label=token.deprel,
                       **edge_formatter(token))
            already_added.add(token_id)
        return graph


Instruction:
Implement a Python 3 function for
constructing a Sentence. stream is an iterable over strings where each string is a line in CoNLL - X format.

Response:
def from_conll(this_class, stream):
        """Construct a Sentence. stream is an iterable over strings where
        each string is a line in CoNLL-X format. If there are multiple
        sentences in this stream, we only return the first one."""
        stream = iter(stream)
        sentence = this_class()
        for line in stream:
            line = line.strip()
            if line:
                sentence.append(Token.from_conll(line))
            elif sentence:
                return sentence
        return sentence


Instruction:
How would you implement a function in Python 3 that
constructs a Sentence from a Stanford Dependency file.

Response:
def from_stanford_dependencies(this_class, stream, tree,
                                   include_erased=False, include_punct=True):
        """Construct a Sentence. stream is an iterable over strings
        where each string is a line representing a Stanford Dependency
        as in the output of the command line Stanford Dependency tool:

            deprel(gov-index, dep-depindex)

        The corresponding Penn Treebank formatted tree must be provided
        as well."""
        stream = iter(stream)
        sentence = this_class()
        covered_indices = set()
        tags_and_words = ptb_tags_and_words_re.findall(tree)
        # perform some basic cleanups
        tags_and_words = [(tag, word.replace(r'\/', '/'))
                          for (tag, word) in tags_and_words if tag != '-NONE-']
        for line in stream:
            if not line.strip():
                if sentence:
                    # empty line means the sentence is over
                    break
                else:
                    continue
            line = line.replace(r'\/', '/')
            matches = deps_re.findall(line)
            assert len(matches) == 1
            (deprel, gov_form, head, gov_is_copy, form, index,
             dep_is_copy) = matches[0]
            index = int(index)
            tag, word = tags_and_words[index - 1]
            assert form == word
            covered_indices.add(index)

            if not include_punct and deprel == 'punct':
                continue
            if gov_is_copy or dep_is_copy:
                extra = {}
                if gov_is_copy:
                    extra['gov_is_copy'] = len(gov_is_copy)
                if dep_is_copy:
                    extra['dep_is_copy'] = len(dep_is_copy)
            else:
                extra = None
            token = Token(index, form, None, tag, tag, None, int(head),
                          deprel, None, None, extra)
            sentence.append(token)

        if include_erased:
            # look through words in the tree to see if any of them
            # were erased
            for index, (tag, word) in enumerate(tags_and_words, 1):
                if index in covered_indices:
                    continue
                token = Token(index, word, None, tag, tag, None, 0,
                              'erased', None, None, None)
                sentence.append(token)

        sentence.sort()
        return sentence


Instruction:
Here you have a function in Python 3, explain what it does
def from_conll(this_class, stream):
        stream = iter(stream)
        corpus = this_class()
        while 1:
            # read until we get an empty sentence
            sentence = Sentence.from_conll(stream)
            if sentence:
                corpus.append(sentence)
            else:
                break
        return corpus

Response:
Construct a Corpus. stream is an iterable over strings where
        each string is a line in CoNLL - X format.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def from_stanford_dependencies(this_class, stream, trees,
                                   include_erased=False, include_punct=True):
        """Construct a Corpus. stream is an iterable over strings where
        each string is a line representing a Stanford Dependency as in
        the output of the command line Stanford Dependency tool:

            deprel(gov-index, dep-depindex)

        Sentences are separated by blank lines. A corresponding list of
        Penn Treebank formatted trees must be provided as well."""
        stream = iter(stream)
        corpus = this_class()
        for tree in trees:
            sentence = Sentence.from_stanford_dependencies(stream,
                                                           tree,
                                                           include_erased,
                                                           include_punct)
            corpus.append(sentence)
        return corpus

Response: Construct a Corpus from a list of trees and a list of UnifiedTrees.


Instruction:
Implement a function in Python 3 to
convert a list of Penn Treebank formatted trees into Stanford Dependencies.

Response:
def convert_trees(self, ptb_trees, representation='basic',
                      include_punct=True, include_erased=False, universal=True,
                      debug=False):
        """Convert a list of Penn Treebank formatted trees (ptb_trees)
        into Stanford Dependencies. The dependencies are represented
        as a list of sentences, where each sentence is itself a list of
        Token objects.

        Currently supported representations are 'basic', 'collapsed',
        'CCprocessed', and 'collapsedTree' which behave the same as they
        in the CoreNLP command line tools. (note that in the online
        CoreNLP demo, 'collapsed' is called 'enhanced')

        Setting debug=True will cause debugging information (including
        the java command run to be printed."""
        self._raise_on_bad_representation(representation)
        input_file = tempfile.NamedTemporaryFile(delete=False)
        try:
            for ptb_tree in ptb_trees:
                self._raise_on_bad_input(ptb_tree)
                tree_with_line_break = ptb_tree + "\n"
                input_file.write(tree_with_line_break.encode("utf-8"))
            input_file.flush()
            input_file.close()

            command = [self.java_command,
                       '-ea',
                       '-cp', self.jar_filename,
                       JAVA_CLASS_NAME,
                       '-' + representation,
                       '-treeFile', input_file.name]
            # if we're including erased, we want to include punctuation
            # since otherwise we won't know what SD considers punctuation
            if include_punct or include_erased:
                command.append('-keepPunct')
            if not universal:
                command.append('-originalDependencies')
            if debug:
                print('Command:', ' '.join(command))
            sd_process = subprocess.Popen(command, stdout=subprocess.PIPE,
                                          stderr=subprocess.PIPE,
                                          universal_newlines=True)
            return_code = sd_process.wait()
            stderr = sd_process.stderr.read()
            stdout = sd_process.stdout.read()

            if debug:
                print("stdout: {%s}" % stdout)
                print("stderr: {%s}" % stderr)
                print('Exit code:', return_code)

            self._raise_on_bad_exit_or_output(return_code, stderr)
        finally:
            os.remove(input_file.name)

        try:
            sentences = Corpus.from_stanford_dependencies(stdout.splitlines(),
                                                          ptb_trees,
                                                          include_erased,
                                                          include_punct)
            for sentence, ptb_tree in zip(sentences, ptb_trees):
                if len(sentence) == 0:
                    raise ValueError("Invalid PTB tree: %r" % ptb_tree)
        except:
            print("Error during conversion")
            if not debug:
                print("stdout: {%s}" % stdout)
                print("stderr: {%s}" % stderr)
            raise

        assert len(sentences) == len(ptb_trees), \
            "Only got %d sentences from Stanford Dependencies when " \
            "given %d trees." % (len(sentences), len(ptb_trees))
        return sentences


Instruction:
Can you write a function in Python 3 where it
returns an endpoint object from a name.

Response:
def endpoint_from_name(endpoint_name):
    """The object used for interacting with the named relations, or None.
    """
    if endpoint_name is None:
        return None
    factory = relation_factory(endpoint_name)
    if factory:
        return factory.from_name(endpoint_name)


Instruction:
Can you create a Python 3 function that
returns the Endpoint object used for interacting with relations tied to a flag.

Response:
def endpoint_from_flag(flag):
    """The object used for interacting with relations tied to a flag, or None.
    """
    relation_name = None
    value = _get_flag_value(flag)
    if isinstance(value, dict) and 'relation' in value:
        # old-style RelationBase
        relation_name = value['relation']
    elif flag.startswith('endpoint.'):
        # new-style Endpoint
        relation_name = flag.split('.')[1]
    elif '.' in flag:
        # might be an unprefixed new-style Endpoint
        relation_name = flag.split('.')[0]
        if relation_name not in hookenv.relation_types():
            return None
    if relation_name:
        factory = relation_factory(relation_name)
        if factory:
            return factory.from_flag(flag)
    return None


Instruction:
Can you create a Python 3 function that
gets the RelationFactory for the given relation name.

Response:
def relation_factory(relation_name):
    """Get the RelationFactory for the given relation name.

    Looks for a RelationFactory in the first file matching:
    ``$CHARM_DIR/hooks/relations/{interface}/{provides,requires,peer}.py``
    """
    role, interface = hookenv.relation_to_role_and_interface(relation_name)
    if not (role and interface):
        hookenv.log('Unable to determine role and interface for relation '
                    '{}'.format(relation_name), hookenv.ERROR)
        return None
    return _find_relation_factory(_relation_module(role, interface))


Instruction:
Can you generate the documentation for the following Python 3 function
def _relation_module(role, interface):
    _append_path(hookenv.charm_dir())
    _append_path(os.path.join(hookenv.charm_dir(), 'hooks'))
    base_module = 'relations.{}.{}'.format(interface, role)
    for module in ('reactive.{}'.format(base_module), base_module):
        if module in sys.modules:
            break
        try:
            importlib.import_module(module)
            break
        except ImportError:
            continue
    else:
        hookenv.log('Unable to find implementation for relation: '
                    '{} of {}'.format(role, interface), hookenv.ERROR)
        return None
    return sys.modules[module]

Response: Return module for relation based on its role and interface.


Instruction:
Can you tell what is the following Python 3 function doing
def _find_relation_factory(module):
    if not module:
        return None

    # All the RelationFactory subclasses
    candidates = [o for o in (getattr(module, attr) for attr in dir(module))
                  if (o is not RelationFactory and
                      o is not RelationBase and
                      isclass(o) and
                      issubclass(o, RelationFactory))]

    # Filter out any factories that are superclasses of another factory
    # (none of the other factories subclass it). This usually makes
    # the explict check for RelationBase and RelationFactory unnecessary.
    candidates = [c1 for c1 in candidates
                  if not any(issubclass(c2, c1) for c2 in candidates
                             if c1 is not c2)]

    if not candidates:
        hookenv.log('No RelationFactory found in {}'.format(module.__name__),
                    hookenv.WARNING)
        return None

    if len(candidates) > 1:
        raise RuntimeError('Too many RelationFactory found in {}'
                           ''.format(module.__name__))

    return candidates[0]

Response: Attempt to find a RelationFactory subclass in the module.


Instruction:
Given the following Python 3 function, write the documentation
def _migrate_conversations():  # noqa
    for key, data in unitdata.kv().getrange('reactive.conversations.').items():
        if 'local-data' in key:
            continue
        if 'namespace' in data:
            continue
        relation_name = data.pop('relation_name')
        if data['scope'] == scopes.GLOBAL:
            data['namespace'] = relation_name
            unitdata.kv().set(key, data)
        else:
            # split the conv based on the relation ID
            new_keys = []
            for rel_id in hookenv.relation_ids(relation_name):
                new_key = Conversation._key(rel_id, data['scope'])
                new_units = set(hookenv.related_units(rel_id)) & set(data['units'])
                if new_units:
                    unitdata.kv().set(new_key, {
                        'namespace': rel_id,
                        'scope': data['scope'],
                        'units': sorted(new_units),
                    })
                    new_keys.append(new_key)
            unitdata.kv().unset(key)
            # update the states pointing to the old conv key to point to the
            # (potentially multiple) new key(s)
            for flag in get_flags():
                value = _get_flag_value(flag)
                if not value:
                    continue
                if key not in value['conversations']:
                    continue
                value['conversations'].remove(key)
                value['conversations'].extend(new_keys)
                set_flag(flag, value)

Response:
Migrate all conversations in the SERVICE
    to the new format.


Instruction:
How would you code a function in Python 3 to
invoke a method on the class implementing a relation via the CLI

Response:
def relation_call(method, relation_name=None, flag=None, state=None, *args):
    """Invoke a method on the class implementing a relation via the CLI"""
    if relation_name:
        relation = relation_from_name(relation_name)
        if relation is None:
            raise ValueError('Relation not found: %s' % relation_name)
    elif flag or state:
        relation = relation_from_flag(flag or state)
        if relation is None:
            raise ValueError('Relation not found: %s' % (flag or state))
    else:
        raise ValueError('Must specify either relation_name or flag')
    result = getattr(relation, method)(*args)
    if isinstance(relation, RelationBase) and method == 'conversations':
        # special case for conversations to make them work from CLI
        result = [c.scope for c in result]
    return result


Instruction:
Can you write a function in Python 3 where it
returns an Endpoint from a flag.

Response:
def from_flag(cls, flag):
        """
        Find relation implementation in the current charm, based on the
        name of an active flag.

        You should not use this method directly.
        Use :func:`endpoint_from_flag` instead.
        """
        value = _get_flag_value(flag)
        if value is None:
            return None
        relation_name = value['relation']
        conversations = Conversation.load(value['conversations'])
        return cls.from_name(relation_name, conversations)


Instruction:
Given the following Python 3 function, write the documentation
def from_name(cls, relation_name, conversations=None):
        if relation_name is None:
            return None
        relation_class = cls._cache.get(relation_name)
        if relation_class:
            return relation_class(relation_name, conversations)
        role, interface = hookenv.relation_to_role_and_interface(relation_name)
        if role and interface:
            relation_class = cls._find_impl(role, interface)
            if relation_class:
                cls._cache[relation_name] = relation_class
                return relation_class(relation_name, conversations)
        return None

Response: Find a relation implementation in the current charm based on the relation name.


Instruction:
Create a Python 3 function to
find the implementation based on its role and interface.

Response:
def _find_impl(cls, role, interface):
        """
        Find relation implementation based on its role and interface.
        """
        module = _relation_module(role, interface)
        if not module:
            return None
        return cls._find_subclass(module)


Instruction:
Given the following Python 3 function, write the documentation
def _find_subclass(cls, module):
        for attr in dir(module):
            candidate = getattr(module, attr)
            if (isclass(candidate) and issubclass(candidate, cls) and
                    candidate is not RelationBase):
                return candidate
        return None

Response: Attempt to find a subclass of cls in the given module.


Instruction:
Write a Python 3 script to
get a single conversation by scope

Response:
def conversation(self, scope=None):
        """
        Get a single conversation, by scope, that this relation is currently handling.

        If the scope is not given, the correct scope is inferred by the current
        hook execution context.  If there is no current hook execution context, it
        is assume that there is only a single global conversation scope for this
        relation.  If this relation's scope is not global and there is no current
        hook execution context, then an error is raised.
        """
        if scope is None:
            if self.scope is scopes.UNIT:
                scope = hookenv.remote_unit()
            elif self.scope is scopes.SERVICE:
                scope = hookenv.remote_service_name()
            else:
                scope = self.scope
        if scope is None:
            raise ValueError('Unable to determine default scope: no current hook or global scope')
        for conversation in self._conversations:
            if conversation.scope == scope:
                return conversation
        else:
            raise ValueError("Conversation with scope '%s' not found" % scope)


Instruction:
Can you implement a function in Python 3 that
toggles the state of the related conversation with the given scope.

Response:
def toggle_state(self, state, active=TOGGLE, scope=None):
        """
        Toggle the state for the :class:`Conversation` with the given scope.

        In Python, this is equivalent to::

            relation.conversation(scope).toggle_state(state, active)

        See :meth:`conversation` and :meth:`Conversation.toggle_state`.
        """
        self.conversation(scope).toggle_state(state, active)


Instruction:
How would you implement a function in Python 3 that
sets data for the remote end of the current conversation with the given scope.

Response:
def set_remote(self, key=None, value=None, data=None, scope=None, **kwdata):
        """
        Set data for the remote end(s) of the :class:`Conversation` with the given scope.

        In Python, this is equivalent to::

            relation.conversation(scope).set_remote(key, value, data, scope, **kwdata)

        See :meth:`conversation` and :meth:`Conversation.set_remote`.
        """
        self.conversation(scope).set_remote(key, value, data, **kwdata)


Instruction:
Explain what the following Python 3 code does
def get_remote(self, key, default=None, scope=None):
        return self.conversation(scope).get_remote(key, default)

Response: Get data from the remote end of the conversation with the given key.


Instruction:
Can you generate the documentation for the following Python 3 function
def set_local(self, key=None, value=None, data=None, scope=None, **kwdata):
        self.conversation(scope).set_local(key, value, data, **kwdata)

Response: Locally store some data namespaced by the current or given conversation scope.


Instruction:
Explain what the following Python 3 code does
def get_local(self, key, default=None, scope=None):
        return self.conversation(scope).get_local(key, default)

Response: Retrieve some data previously set via set_local.


Instruction:
Write a Python 3 function that can
return the set of relation IDs that this conversation is communicating with.

Response:
def relation_ids(self):
        """
        The set of IDs of the specific relation instances that this conversation
        is communicating with.
        """
        if self.scope == scopes.GLOBAL:
            # the namespace is the relation name and this conv speaks for all
            # connected instances of that relation
            return hookenv.relation_ids(self.namespace)
        else:
            # the namespace is the relation ID
            return [self.namespace]


Instruction:
Here you have a function in Python 3, explain what it does
def join(cls, scope):
        relation_name = hookenv.relation_type()
        relation_id = hookenv.relation_id()
        unit = hookenv.remote_unit()
        service = hookenv.remote_service_name()
        if scope is scopes.UNIT:
            scope = unit
            namespace = relation_id
        elif scope is scopes.SERVICE:
            scope = service
            namespace = relation_id
        else:
            namespace = relation_name
        key = cls._key(namespace, scope)
        data = unitdata.kv().get(key, {'namespace': namespace, 'scope': scope, 'units': []})
        conversation = cls.deserialize(data)
        conversation.units.add(unit)
        unitdata.kv().set(key, cls.serialize(conversation))
        return conversation

Response: Get or create a conversation for the given scope and active hook context.


Instruction:
Can you generate the documentation for the following Python 3 function
def depart(self):
        unit = hookenv.remote_unit()
        self.units.remove(unit)
        if self.units:
            unitdata.kv().set(self.key, self.serialize(self))
        else:
            unitdata.kv().unset(self.key)

Response: Removes the current remote unit from the current conversation context.


Instruction:
Implement a function in Python 3 to
serialize a conversation instance for storage.

Response:
def serialize(cls, conversation):
        """
        Serialize a conversation instance for storage.
        """
        return {
            'namespace': conversation.namespace,
            'units': sorted(conversation.units),
            'scope': conversation.scope,
        }


Instruction:
Given the following Python 3 function, write the documentation
def load(cls, keys):
        conversations = []
        for key in keys:
            conversation = unitdata.kv().get(key)
            if conversation:
                conversations.append(cls.deserialize(conversation))
        return conversations

Response: Load a set of conversations by their keys.


Instruction:
Implement a function in Python 3 to
activate and put this conversation into the given state.

Response:
def set_state(self, state):
        """
        Activate and put this conversation into the given state.

        The relation name will be interpolated in the state name, and it is
        recommended that it be included to avoid conflicts with states from
        other relations.  For example::

            conversation.set_state('{relation_name}.state')

        If called from a converation handling the relation "foo", this will
        activate the "foo.state" state, and will add this conversation to
        that state.

        Note: This uses :mod:`charmhelpers.core.unitdata` and requires that
        :meth:`~charmhelpers.core.unitdata.Storage.flush` be called.
        """
        state = state.format(relation_name=self.relation_name)
        value = _get_flag_value(state, {
            'relation': self.relation_name,
            'conversations': [],
        })
        if self.key not in value['conversations']:
            value['conversations'].append(self.key)
        set_flag(state, value)


Instruction:
Can you tell what is the following Python 3 function doing
def remove_state(self, state):
        state = state.format(relation_name=self.relation_name)
        value = _get_flag_value(state)
        if not value:
            return
        if self.key in value['conversations']:
            value['conversations'].remove(self.key)
        if value['conversations']:
            set_flag(state, value)
        else:
            clear_flag(state)

Response:
Removes this conversation from the given state and potentially
            deactivate the state if no more conversations are in it.


Instruction:
Write a Python 3 script for
testing if this conversation is in the given state.

Response:
def is_state(self, state):
        """
        Test if this conversation is in the given state.
        """
        state = state.format(relation_name=self.relation_name)
        value = _get_flag_value(state)
        if not value:
            return False
        return self.key in value['conversations']


Instruction:
Given the following Python 3 function, write the documentation
def toggle_state(self, state, active=TOGGLE):
        if active is TOGGLE:
            active = not self.is_state(state)
        if active:
            self.set_state(state)
        else:
            self.remove_state(state)

Response: Toggle the given state for this conversation.


Instruction:
Write a Python 3 script for
setting data for the remote end of this conversation.

Response:
def set_remote(self, key=None, value=None, data=None, **kwdata):
        """
        Set data for the remote end(s) of this conversation.

        Data can be passed in either as a single dict, or as key-word args.

        Note that, in Juju, setting relation data is inherently service scoped.
        That is, if the conversation only includes a single unit, the data will
        still be set for that unit's entire service.

        However, if this conversation's scope encompasses multiple services,
        the data will be set for all of those services.

        :param str key: The name of a field to set.
        :param value: A value to set. This value must be json serializable.
        :param dict data: A mapping of keys to values.
        :param **kwdata: A mapping of keys to values, as keyword arguments.
        """
        if data is None:
            data = {}
        if key is not None:
            data[key] = value
        data.update(kwdata)
        if not data:
            return
        for relation_id in self.relation_ids:
            hookenv.relation_set(relation_id, data)


Instruction:
Write a Python 3 script for
getting a value from the remote end of this conversation.

Response:
def get_remote(self, key, default=None):
        """
        Get a value from the remote end(s) of this conversation.

        Note that if a conversation's scope encompasses multiple units, then
        those units are expected to agree on their data, whether that is through
        relying on a single leader to set the data or by all units eventually
        converging to identical data.  Thus, this method returns the first
        value that it finds set by any of its units.
        """
        cur_rid = hookenv.relation_id()
        departing = hookenv.hook_name().endswith('-relation-departed')
        for relation_id in self.relation_ids:
            units = hookenv.related_units(relation_id)
            if departing and cur_rid == relation_id:
                # Work around the fact that Juju 2.0 doesn't include the
                # departing unit in relation-list during the -departed hook,
                # by adding it back in ourselves.
                units.append(hookenv.remote_unit())
            for unit in units:
                if unit not in self.units:
                    continue
                value = hookenv.relation_get(key, unit, relation_id)
                if value:
                    return value
        return default


Instruction:
Given the following Python 3 function, write the documentation
def set_local(self, key=None, value=None, data=None, **kwdata):
        if data is None:
            data = {}
        if key is not None:
            data[key] = value
        data.update(kwdata)
        if not data:
            return
        unitdata.kv().update(data, prefix='%s.%s.' % (self.key, 'local-data'))

Response: Set the local data associated with this conversation.


Instruction:
Explain what the following Python 3 code does
def get_local(self, key, default=None):
        key = '%s.%s.%s' % (self.key, 'local-data', key)
        return unitdata.kv().get(key, default)

Response: Retrieve some data from the local - data store for this conversation.


Instruction:
Create a Python 3 function to
set the given flag as active.

Response:
def set_flag(flag, value=None):
    """set_flag(flag)
    Set the given flag as active.

    :param str flag: Name of flag to set.

    .. note:: **Changes to flags are reset when a handler crashes.** Changes to
       flags happen immediately, but they are only persisted at the end of a
       complete and successful run of the reactive framework. All unpersisted
       changes are discarded when a hook crashes.
    """
    old_flags = get_flags()
    unitdata.kv().update({flag: value}, prefix='reactive.states.')
    if flag not in old_flags:
        tracer().set_flag(flag)
        FlagWatch.change(flag)
        trigger = _get_trigger(flag, None)
        for flag_name in trigger['set_flag']:
            set_flag(flag_name)
        for flag_name in trigger['clear_flag']:
            clear_flag(flag_name)


Instruction:
Can you implement a function in Python 3 that
clears the flag in the specified node.

Response:
def clear_flag(flag):
    """
    Clear / deactivate a flag.

    :param str flag: Name of flag to set.

    .. note:: **Changes to flags are reset when a handler crashes.** Changes to
       flags happen immediately, but they are only persisted at the end of a
       complete and successful run of the reactive framework. All unpersisted
       changes are discarded when a hook crashes.
    """
    old_flags = get_flags()
    unitdata.kv().unset('reactive.states.%s' % flag)
    unitdata.kv().set('reactive.dispatch.removed_state', True)
    if flag in old_flags:
        tracer().clear_flag(flag)
        FlagWatch.change(flag)
        trigger = _get_trigger(None, flag)
        for flag_name in trigger['set_flag']:
            set_flag(flag_name)
        for flag_name in trigger['clear_flag']:
            clear_flag(flag_name)


Instruction:
Implement a function in Python 3 to
register a trigger to set or clear a flag when a given flag is set.

Response:
def register_trigger(when=None, when_not=None, set_flag=None, clear_flag=None):
    """
    Register a trigger to set or clear a flag when a given flag is set.

    Note: Flag triggers are handled at the same time that the given flag is set.

    :param str when: Flag to trigger on when it is set.
    :param str when_not: Flag to trigger on when it is cleared.
    :param str set_flag: If given, this flag will be set when `when` is set.
    :param str clear_flag: If given, this flag will be cleared when `when` is set.

    Note: Exactly one of either `when` or `when_not`, and at least one of
    `set_flag` or `clear_flag` must be provided.
    """
    if not any((when, when_not)):
        raise ValueError('Must provide one of when or when_not')
    if all((when, when_not)):
        raise ValueError('Only one of when or when_not can be provided')
    if not any((set_flag, clear_flag)):
        raise ValueError('Must provide at least one of set_flag or clear_flag')
    trigger = _get_trigger(when, when_not)
    if set_flag and set_flag not in trigger['set_flag']:
        trigger['set_flag'].append(set_flag)
    if clear_flag and clear_flag not in trigger['clear_flag']:
        trigger['clear_flag'].append(clear_flag)
    _save_trigger(when, when_not, trigger)


Instruction:
Can you generate the documentation for the following Python 3 function
def get_flags():
    flags = unitdata.kv().getrange('reactive.states.', strip=True) or {}
    return sorted(flags.keys())

Response: Return a list of all flags which are set.


Instruction:
Make a summary of the following Python 3 code
def dispatch(restricted=False):
    FlagWatch.reset()

    def _test(to_test):
        return list(filter(lambda h: h.test(), to_test))

    def _invoke(to_invoke):
        while to_invoke:
            unitdata.kv().set('reactive.dispatch.removed_state', False)
            for handler in list(to_invoke):
                to_invoke.remove(handler)
                hookenv.log('Invoking reactive handler: %s' % handler.id(), level=hookenv.INFO)
                handler.invoke()
                if unitdata.kv().get('reactive.dispatch.removed_state'):
                    # re-test remaining handlers
                    to_invoke = _test(to_invoke)
                    break
        FlagWatch.commit()

    tracer().start_dispatch()

    # When in restricted context, only run hooks for that context.
    if restricted:
        unitdata.kv().set('reactive.dispatch.phase', 'restricted')
        hook_handlers = _test(Handler.get_handlers())
        tracer().start_dispatch_phase('restricted', hook_handlers)
        _invoke(hook_handlers)
        return

    unitdata.kv().set('reactive.dispatch.phase', 'hooks')
    hook_handlers = _test(Handler.get_handlers())
    tracer().start_dispatch_phase('hooks', hook_handlers)
    _invoke(hook_handlers)

    unitdata.kv().set('reactive.dispatch.phase', 'other')
    for i in range(100):
        FlagWatch.iteration(i)
        other_handlers = _test(Handler.get_handlers())
        if i == 0:
            tracer().start_dispatch_phase('other', other_handlers)
        tracer().start_dispatch_iteration(i, other_handlers)
        if not other_handlers:
            break
        _invoke(other_handlers)

    FlagWatch.reset()

Response:
Dispatch registered handlers.

    When dispatching in restricted mode, only matching hook handlers are executed.

    Handlers are dispatched according to the following rules:

    * Handlers are repeatedly tested and invoked in iterations, until the system
      settles into quiescence (that is, until no new handlers match to be invoked).

    * In the first iteration, :func:`@hook <charms.reactive.decorators.hook>`
      and :func:`@action <charms.reactive.decorators.action>` handlers will
      be invoked, if they match.

    * In subsequent iterations, other handlers are invoked, if they match.

    * Added flags will not trigger new handlers until the next iteration,
      to ensure that chained flags are invoked in a predictable order.

    * Removed flags will cause the current set of matched handlers to be
      re-tested, to ensure that no handler is invoked after its matching
      flag has been removed.

    * Other than the guarantees mentioned above, the order in which matching
      handlers are invoked is undefined.

    * Flags are preserved between hook and action invocations, and all matching
      handlers are re-invoked for every hook and action.  There are
      :doc:`decorators <charms.reactive.decorators>` and
      :doc:`helpers <charms.reactive.helpers>`
      to prevent unnecessary reinvocations, such as
      :func:`~charms.reactive.decorators.only_once`.


Instruction:
How would you code a function in Python 3 to
discover handlers based on convention.

Response:
def discover():
    """
    Discover handlers based on convention.

    Handlers will be loaded from the following directories and their subdirectories:

      * ``$CHARM_DIR/reactive/``
      * ``$CHARM_DIR/hooks/reactive/``
      * ``$CHARM_DIR/hooks/relations/``

    They can be Python files, in which case they will be imported and decorated
    functions registered.  Or they can be executables, in which case they must
    adhere to the :class:`ExternalHandler` protocol.
    """
    # Add $CHARM_DIR and $CHARM_DIR/hooks to sys.path so
    # 'import reactive.leadership', 'import relations.pgsql' works
    # as expected, as well as relative imports like 'import ..leadership'
    # or 'from . import leadership'. Without this, it becomes difficult
    # for layers to access APIs provided by other layers. This addition
    # needs to remain in effect, in case discovered modules are doing
    # late imports.
    _append_path(hookenv.charm_dir())
    _append_path(os.path.join(hookenv.charm_dir(), 'hooks'))

    for search_dir in ('reactive', 'hooks/reactive', 'hooks/relations'):
        search_path = os.path.join(hookenv.charm_dir(), search_dir)
        for dirpath, dirnames, filenames in os.walk(search_path):
            for filename in filenames:
                filepath = os.path.join(dirpath, filename)
                _register_handlers_from_file(search_path, filepath)