Instruction:
Can you implement a function in Python 3 that
generates a DFA state for the given flatterm.

Response:
def _generate_net(cls, flatterm: FlatTerm, final_label: T) -> _State[T]:
        """Generates a DFA matching the given pattern."""
        # Capture the last sequence wildcard for every level of operation nesting on a stack
        # Used to add backtracking edges in case the "match" fails later
        last_wildcards = [None]
        # Generate a fail state for every level of nesting to backtrack to a sequence wildcard in a parent Expression
        # in case no match can be found
        fail_states = [None]
        operand_counts = [0]
        root = state = _State()
        states = {root.id: root}

        for term in flatterm:
            if operand_counts[-1] >= 0:
                operand_counts[-1] += 1

            # For wildcards, generate a chain of #min_count Wildcard edges
            # If the wildcard is unbounded (fixed_size = False),
            # add a wildcard self loop at the end
            if isinstance(term, Wildcard):
                # Generate a chain of #min_count Wildcard edges
                for _ in range(term.min_count):
                    state = cls._create_child_state(state, Wildcard)
                    states[state.id] = state
                # If it is a sequence wildcard, add a self loop
                if not term.fixed_size:
                    state[Wildcard] = state
                    last_wildcards[-1] = state
                    operand_counts[-1] = -1
            else:
                state = cls._create_child_state(state, term)
                states[state.id] = state
                if is_operation(term):
                    fail_state = None
                    if last_wildcards[-1] or fail_states[-1]:
                        last_fail_state = (
                            fail_states[-1]
                            if not isinstance(fail_states[-1], list) else fail_states[-1][operand_counts[-1]]
                        )
                        if term.arity.fixed_size:
                            fail_state = _State()
                            states[fail_state.id] = fail_state
                            new_fail_states = [fail_state]
                            for _ in range(term.arity.min_count):
                                new_fail_state = _State()
                                states[new_fail_state.id] = new_fail_state
                                fail_state[Wildcard] = new_fail_state
                                fail_state = new_fail_state
                                new_fail_states.append(new_fail_state)
                            fail_state[OPERATION_END] = last_wildcards[-1] or last_fail_state
                            fail_state = new_fail_states
                        else:
                            fail_state = _State()
                            states[fail_state.id] = fail_state
                            fail_state[OPERATION_END] = last_wildcards[-1] or last_fail_state
                            fail_state[Wildcard] = fail_state
                    fail_states.append(fail_state)
                    last_wildcards.append(None)
                    operand_counts.append(0)
                elif term == OPERATION_END:
                    fail_states.pop()
                    last_wildcards.pop()
                    operand_counts.pop()

            if last_wildcards[-1] != state:
                if last_wildcards[-1]:
                    state[EPSILON] = last_wildcards[-1]
                elif fail_states[-1]:
                    last_fail_state = (
                        fail_states[-1]
                        if not isinstance(fail_states[-1], list) else fail_states[-1][operand_counts[-1]]
                    )
                    state[EPSILON] = last_fail_state

        state.payload = [final_label]

        return cls._convert_nfa_to_dfa(root, states)


Instruction:
Given the following Python 3 function, write the documentation
def match(self, subject: Union[Expression, FlatTerm]) -> Iterator[Tuple[T, Substitution]]:
        for index in self._match(subject):
            pattern, label = self._patterns[index]
            subst = Substitution()
            if subst.extract_substitution(subject, pattern.expression):
                for constraint in pattern.constraints:
                    if not constraint(subst):
                        break
                else:
                    yield label, subst

Response: Match the given subject against all patterns in the net.


Instruction:
Write a Python 3 script to
check if the given subject matches any pattern in the net.

Response:
def is_match(self, subject: Union[Expression, FlatTerm]) -> bool:
        """Check if the given subject matches any pattern in the net.

        Args:
            subject:
                The subject that is matched. Must be constant.

        Returns:
            True, if any pattern matches the subject.
        """
        try:
            next(self.match(subject))
        except StopIteration:
            return False
        return True


Instruction:
Write a Python 3 script for
rendering the discrimination net as graphviz digraph.

Response:
def as_graph(self) -> Digraph:  # pragma: no cover
        """Renders the discrimination net as graphviz digraph."""
        if Digraph is None:
            raise ImportError('The graphviz package is required to draw the graph.')
        dot = Digraph()

        nodes = set()
        queue = [self._root]
        while queue:
            state = queue.pop(0)
            if not state.payload:
                dot.node('n{!s}'.format(state.id), '', {'shape': ('circle' if state else 'doublecircle')})
            else:
                dot.node('n{!s}'.format(state.id), '\n'.join(map(str, state.payload)), {'shape': 'box'})

            for next_state in state.values():
                if next_state.id not in nodes:
                    queue.append(next_state)
                    nodes.add(state.id)

        nodes = set()
        queue = [self._root]
        while queue:
            state = queue.pop(0)
            if state.id in nodes:
                continue
            nodes.add(state.id)

            for (label, other) in state.items():
                dot.edge('n{!s}'.format(state.id), 'n{!s}'.format(other.id), _term_str(label))
                if other.id not in nodes:
                    queue.append(other)

        return dot


Instruction:
Explain what the following Python 3 code does
def add(self, pattern: Pattern) -> int:
        inner = pattern.expression
        if self.operation is None:
            if not isinstance(inner, Operation) or isinstance(inner, CommutativeOperation):
                raise TypeError("Pattern must be a non-commutative operation.")
            self.operation = type(inner)
        elif not isinstance(inner, self.operation):
            raise TypeError(
                "All patterns must be the same operation, expected {} but got {}".format(self.operation, type(inner))
            )

        if op_len(inner) < 3:
            raise ValueError("Pattern has not enough operands.")

        operands = list(op_iter(inner))

        first_name = self._check_wildcard_and_get_name(operands[0])
        last_name = self._check_wildcard_and_get_name(operands[-1])

        index = len(self._patterns)
        self._patterns.append((pattern, first_name, last_name))

        flatterm = FlatTerm.merged(*(FlatTerm(o) for o in operands[1:-1]))
        self._net.add(flatterm, index)

        return index

Response: Adds a pattern that will be recognized by the matcher.


Instruction:
Write a Python 3 function that can
check if a pattern can be matched with a sequence matcher.

Response:
def can_match(cls, pattern: Pattern) -> bool:
        """Check if a pattern can be matched with a sequence matcher.

        Args:
            pattern:
                The pattern to check.

        Returns:
            True, iff the pattern can be matched with a sequence matcher.
        """
        if not isinstance(pattern.expression, Operation) or isinstance(pattern.expression, CommutativeOperation):
            return False

        if op_len(pattern.expression) < 3:
            return False

        first, *_, last = op_iter(pattern.expression)

        try:
            cls._check_wildcard_and_get_name(first)
            cls._check_wildcard_and_get_name(last)
        except ValueError:
            return False

        return True


Instruction:
Explain what the following Python 3 code does
def match(self, subject: Expression) -> Iterator[Tuple[Pattern, Substitution]]:
        if not isinstance(subject, self.operation):
            return

        subjects = list(op_iter(subject))
        flatterms = [FlatTerm(o) for o in subjects]

        for i in range(len(flatterms)):
            flatterm = FlatTerm.merged(*flatterms[i:])

            for index in self._net._match(flatterm, collect=True):
                match_index = self._net._patterns[index][1]
                pattern, first_name, last_name = self._patterns[match_index]
                operand_count = op_len(pattern.expression) - 2
                expr_operands = subjects[i:i + operand_count]
                patt_operands = list(op_iter(pattern.expression))[1:-1]

                substitution = Substitution()
                if not all(itertools.starmap(substitution.extract_substitution, zip(expr_operands, patt_operands))):
                    continue

                try:
                    if first_name is not None:
                        substitution.try_add_variable(first_name, tuple(subjects[:i]))
                    if last_name is not None:
                        substitution.try_add_variable(last_name, tuple(subjects[i + operand_count:]))
                except ValueError:
                    continue

                for constraint in pattern.constraints:
                    if not constraint(substitution):
                        break
                else:
                    yield pattern, substitution

Response: Match the given subject against all patterns in the sequence matcher.


Instruction:
Can you generate the documentation for the following Python 3 function
def match(subject: Expression, pattern: Pattern) -> Iterator[Substitution]:
    if not is_constant(subject):
        raise ValueError("The subject for matching must be constant.")
    global_constraints = [c for c in pattern.constraints if not c.variables]
    local_constraints = set(c for c in pattern.constraints if c.variables)
    for subst in _match([subject], pattern.expression, Substitution(), local_constraints):
        for constraint in global_constraints:
            if not constraint(subst):
                break
        else:
            yield subst

Response: r Returns an iterator over the possible match substitutions for the given subject and pattern.


Instruction:
Here you have a function in Python 3, explain what it does
def match_anywhere(subject: Expression, pattern: Pattern) -> Iterator[Tuple[Substitution, Tuple[int, ...]]]:
    if not is_constant(subject):
        raise ValueError("The subject for matching must be constant.")
    for child, pos in preorder_iter_with_position(subject):
        if match_head(child, pattern):
            for subst in match(child, pattern):
                yield subst, pos

Response: Tries to match the given pattern to the any subexpression of the given subject.


Instruction:
Create a Python 3 function to
give a list of subjects and an operation that is partitoning for the variable part of the operands. Given a partitoning for the variable part of the operands. Given a partitoning for the optional parts each pattern gets assigned.

Response:
def _build_full_partition(
        optional_parts, sequence_var_partition: Sequence[int], subjects: Sequence[Expression], operation: Operation
) -> List[Sequence[Expression]]:
    """Distribute subject operands among pattern operands.

    Given a partitoning for the variable part of the operands (i.e. a list of how many extra operands each sequence
    variable gets assigned).
    """
    i = 0
    var_index = 0
    opt_index = 0
    result = []
    for operand in op_iter(operation):
        wrap_associative = False
        if isinstance(operand, Wildcard):
            count = operand.min_count if operand.optional is None else 0
            if not operand.fixed_size or isinstance(operation, AssociativeOperation):
                count += sequence_var_partition[var_index]
                var_index += 1
                wrap_associative = operand.fixed_size and operand.min_count
            elif operand.optional is not None:
                count = optional_parts[opt_index]
                opt_index += 1
        else:
            count = 1

        operand_expressions = list(op_iter(subjects))[i:i + count]
        i += count

        if wrap_associative and len(operand_expressions) > wrap_associative:
            fixed = wrap_associative - 1
            operand_expressions = tuple(operand_expressions[:fixed]) + (
                create_operation_expression(operation, operand_expressions[fixed:]),
            )

        result.append(operand_expressions)

    return result


Instruction:
Here you have a function in Python 3, explain what it does
def grouped(self):
        for _ in self._match(self.matcher.root):
            yield list(self._internal_iter())

Response: Yields the matches grouped by their final state in the automaton.


Instruction:
Can you implement a function in Python 3 that
adds a new pattern to the matcher.

Response:
def add(self, pattern: Pattern, label=None) -> None:
        """Add a new pattern to the matcher.

        The optional label defaults to the pattern itself and is yielded during matching. The same pattern can be
        added with different labels which means that every match for the pattern will result in every associated label
        being yielded with that match individually.

        Equivalent patterns with the same label are not added again. However, patterns that are structurally equivalent,
        but have different constraints or different variable names are distinguished by the matcher.

        Args:
            pattern:
                The pattern to add.
            label:
                An optional label for the pattern. Defaults to the pattern itself.
        """
        if label is None:
            label = pattern
        for i, (p, l, _) in enumerate(self.patterns):
            if pattern == p and label == l:
                return i
        # TODO: Avoid renaming in the pattern, use variable indices instead
        renaming = self._collect_variable_renaming(pattern.expression) if self.rename else {}
        self._internal_add(pattern, label, renaming)


Instruction:
Implement a Python 3 function for
adding a new pattern to the matcher.

Response:
def _internal_add(self, pattern: Pattern, label, renaming) -> int:
        """Add a new pattern to the matcher.

        Equivalent patterns are not added again. However, patterns that are structurally equivalent,
        but have different constraints or different variable names are distinguished by the matcher.

        Args:
            pattern: The pattern to add.

        Returns:
            The internal id for the pattern. This is mainly used by the :class:`CommutativeMatcher`.
        """
        pattern_index = len(self.patterns)
        renamed_constraints = [c.with_renamed_vars(renaming) for c in pattern.local_constraints]
        constraint_indices = [self._add_constraint(c, pattern_index) for c in renamed_constraints]
        self.patterns.append((pattern, label, constraint_indices))
        self.pattern_vars.append(renaming)
        pattern = rename_variables(pattern.expression, renaming)
        state = self.root
        patterns_stack = [deque([pattern])]

        self._process_pattern_stack(state, patterns_stack, renamed_constraints, pattern_index)

        return pattern_index


Instruction:
Can you generate the documentation for the following Python 3 function
def match(self, subject: Expression) -> Iterator[Tuple[Expression, Substitution]]:
        return _MatchIter(self, subject)

Response: Match the subject against all the patterns.


Instruction:
Can you generate the documentation for the following Python 3 function
def _collect_variable_renaming(
            cls, expression: Expression, position: List[int]=None, variables: Dict[str, str]=None
    ) -> Dict[str, str]:
        """Return renaming for the variables in the expression.

        The variable names are generated according to the position of the variable in the expression. The goal is to
        rename variables in structurally identical patterns so that the automaton contains less redundant states.
        """
        if position is None:
            position = [0]
        if variables is None:
            variables = {}
        if getattr(expression, 'variable_name', False):
            if expression.variable_name not in variables:
                variables[expression.variable_name] = cls._get_name_for_position(position, variables.values())
        position[-1] += 1
        if isinstance(expression, Operation):
            if isinstance(expression, CommutativeOperation):
                for operand in op_iter(expression):
                    position.append(0)
                    cls._collect_variable_renaming(operand, position, variables)
                    position.pop()
            else:
                for operand in op_iter(expression):
                    cls._collect_variable_renaming(operand, position, variables)

        return variables

Response: Return renaming for the variables in the expression.


Instruction:
Create a Python 3 function for
adding a new rule to the replacer.

Response:
def add(self, rule: 'functions.ReplacementRule') -> None:
        """Add a new rule to the replacer.

        Args:
            rule:
                The rule to add.
        """
        self.matcher.add(rule.pattern, rule.replacement)


Instruction:
Can you tell what is the following Python 3 function doing
def replace(self, expression: Expression, max_count: int=math.inf) -> Union[Expression, Sequence[Expression]]:
        replaced = True
        replace_count = 0
        while replaced and replace_count < max_count:
            replaced = False
            for subexpr, pos in preorder_iter_with_position(expression):
                try:
                    replacement, subst = next(iter(self.matcher.match(subexpr)))
                    result = replacement(**subst)
                    expression = functions.replace(expression, pos, result)
                    replaced = True
                    break
                except StopIteration:
                    pass
            replace_count += 1
        return expression

Response: Replaces all occurrences of the patterns according to the replacement rules.


Instruction:
Explain what the following Python 3 code does
def replace_post_order(self, expression: Expression) -> Union[Expression, Sequence[Expression]]:
        return self._replace_post_order(expression)[0]

Response: Replaces all occurrences of the patterns according to the replacement rules.


Instruction:
Explain what the following Python 3 code does
def bipartite_as_graph(self) -> Graph:  # pragma: no cover
        if Graph is None:
            raise ImportError('The graphviz package is required to draw the graph.')
        graph = Graph()
        nodes_left = {}  # type: Dict[TLeft, str]
        nodes_right = {}  # type: Dict[TRight, str]
        node_id = 0
        for (left, right), value in self.bipartite._edges.items():
            if left not in nodes_left:
                name = 'node{:d}'.format(node_id)
                nodes_left[left] = name
                label = str(self.subjects_by_id[left])
                graph.node(name, label=label)
                node_id += 1
            if right not in nodes_right:
                name = 'node{:d}'.format(node_id)
                nodes_right[right] = name
                label = str(self.automaton.patterns[right][0])
                graph.node(name, label=label)
                node_id += 1
            edge_label = value is not True and str(value) or ''
            graph.edge(nodes_left[left], nodes_right[right], edge_label)
        return graph

Response: Returns a graphviz. Graph representation of this bipartite.


Instruction:
Create a Python 3 function to
return a graphviz. Graph representation of this bipartite.

Response:
def concrete_bipartite_as_graph(self, subjects, patterns) -> Graph:  # pragma: no cover
        """Returns a :class:`graphviz.Graph` representation of this bipartite graph."""
        if Graph is None:
            raise ImportError('The graphviz package is required to draw the graph.')
        bipartite = self._build_bipartite(subjects, patterns)
        graph = Graph()
        nodes_left = {}  # type: Dict[TLeft, str]
        nodes_right = {}  # type: Dict[TRight, str]
        node_id = 0
        for (left, right), value in bipartite._edges.items():
            if left not in nodes_left:
                subject_id, i = left
                name = 'node{:d}'.format(node_id)
                nodes_left[left] = name
                label = '{}, {}'.format(i, self.subjects_by_id[subject_id])
                graph.node(name, label=label)
                node_id += 1
            if right not in nodes_right:
                pattern, i = right
                name = 'node{:d}'.format(node_id)
                nodes_right[right] = name
                label = '{}, {}'.format(i, self.automaton.patterns[pattern][0])
                graph.node(name, label=label)
                node_id += 1
            edge_label = value is not True and str(value) or ''
            graph.edge(nodes_left[left], nodes_right[right], edge_label)
        return graph


Instruction:
Can you generate the documentation for the following Python 3 function
def collect_variables(self, variables: MultisetOfVariables) -> None:
        if self.variable_name is not None:
            variables.add(self.variable_name)

Response: Recursively adds all variables occuring in the expression to the given multiset.


Instruction:
Explain what the following Python 3 code does
def _simplify(cls, operands: List[Expression]) -> bool:

        if cls.associative:
            new_operands = []  # type: List[Expression]
            for operand in operands:
                if isinstance(operand, cls):
                    new_operands.extend(operand.operands)  # type: ignore
                else:
                    new_operands.append(operand)
            operands.clear()
            operands.extend(new_operands)

        if cls.one_identity and len(operands) == 1:
            expr = operands[0]
            if not isinstance(expr, Wildcard) or (expr.min_count == 1 and expr.fixed_size):
                return True

        if cls.commutative:
            operands.sort()

        return False

Response: Flatten the operands of associative or commutative operations.


Instruction:
Given the following Python 3 function, write the documentation
def new(
            name: str,
            arity: Arity,
            class_name: str=None,
            *,
            associative: bool=False,
            commutative: bool=False,
            one_identity: bool=False,
            infix: bool=False
    ) -> Type['Operation']:
        """Utility method to create a new operation type.

        Example:

        >>> Times = Operation.new('*', Arity.polyadic, 'Times', associative=True, commutative=True, one_identity=True)
        >>> Times
        Times['*', Arity(min_count=2, fixed_size=False), associative, commutative, one_identity]
        >>> str(Times(Symbol('a'), Symbol('b')))
        '*(a, b)'

        Args:
            name:
                Name or symbol for the operator. Will be used as name for the new class if
                `class_name` is not specified.
            arity:
                The arity of the operator as explained in the documentation of `Operation`.
            class_name:
                Name for the new operation class to be used instead of name. This argument
                is required if `name` is not a valid python identifier.

        Keyword Args:
            associative:
                See :attr:`~Operation.associative`.
            commutative:
                See :attr:`~Operation.commutative`.
            one_identity:
                See :attr:`~Operation.one_identity`.
            infix:
                See :attr:`~Operation.infix`.

        Raises:
            ValueError: if the class name of the operation is not a valid class identifier.
        """
        class_name = class_name or name
        if not class_name.isidentifier() or keyword.iskeyword(class_name):
            raise ValueError("Invalid identifier for new operator class.")

        return type(
            class_name, (Operation, ), {
                'name': name,
                'arity': arity,
                'associative': associative,
                'commutative': commutative,
                'one_identity': one_identity,
                'infix': infix
            }
        )

Response: Utility method to create a new operation type.


Instruction:
Implement a function in Python 3 to
create a Wildcard that matches a single argument with a default value.

Response:
def optional(name, default) -> 'Wildcard':
        """Create a `Wildcard` that matches a single argument with a default value.

        If the wildcard does not match, the substitution will contain the
        default value instead.

        Args:
            name:
                The name for the wildcard.
            default:
                The default value of the wildcard.

        Returns:
            A n optional wildcard.
        """
        return Wildcard(min_count=1, fixed_size=True, variable_name=name, optional=default)


Instruction:
Explain what the following Python 3 code does
def symbol(name: str=None, symbol_type: Type[Symbol]=Symbol) -> 'SymbolWildcard':
        if isinstance(name, type) and issubclass(name, Symbol) and symbol_type is Symbol:
            return SymbolWildcard(name)
        return SymbolWildcard(symbol_type, variable_name=name)

Response: Create a SymbolWildcard that matches a single Symbol argument.


Instruction:
Here you have a function in Python 3, explain what it does
def parse_response(resp):
        if resp.status_code in [200, 201, 202]:
            return resp.json()
        elif resp.status_code == 204:
            return None
        elif resp.status_code == 400:
            raise error.BadRequestError(resp.text)
        elif resp.status_code == 401:
            raise error.UnauthorizedError(resp.text)
        elif resp.status_code == 403:
            raise error.ForbiddenError(resp.text)
        elif resp.status_code == 404:
            raise error.NotFoundError(resp.text)
        elif resp.status_code == 429:
            raise error.TooManyRequestsError(resp.text)
        elif resp.status_code == 503:
            raise error.ServiceUnavailableError(resp.text)
        else:
            raise error.OptimizelyError(resp.text)

Response: Method to parse the response from the Optimizely API and return the result as JSON.


Instruction:
Create a Python 3 function to
convert python data structures to R equivalents

Response:
def _to_r(o, as_data=False, level=0):
    """Helper function to convert python data structures to R equivalents

    TODO: a single model for transforming to r to handle
    * function args
    * lists as function args
    """
    if o is None:
        return "NA"
    if isinstance(o, basestring):
        return o
    if hasattr(o, "r"):
        # bridge to @property r on GGStatement(s)
        return o.r
    elif isinstance(o, bool):
        return "TRUE" if o else "FALSE"
    elif isinstance(o, (list, tuple)):
        inner = ",".join([_to_r(x, True, level+1) for x in o])
        return "c({})".format(inner) if as_data else inner
    elif isinstance(o, dict):
        inner = ",".join(["{}={}".format(k, _to_r(v, True, level+1))
                         for k, v in sorted(o.iteritems(), key=lambda x: x[0])])
        return "list({})".format(inner) if as_data else inner
    return str(o)


Instruction:
Here you have a function in Python 3, explain what it does
def data_sql(db, sql):
    if not db:
        if sql:
            print "ERR: -db option must be set if using -sql"
        return ""

    cmd = """
    library(RPostgreSQL)
    drv = dbDriver('PostgreSQL')
    con = dbConnect(drv, dbname='%(db_name)s')
    q = "%(query)s"
    data = dbGetQuery(con, q)
    """

    return GGData(cmd % {
        'db_name': db,
        'query': sql
    })

Response: Load file using RPostgreSQL


Instruction:
Make a summary of the following Python 3 code
def ggsave(name, plot, data=None, *args, **kwargs):
    # constants
    kwdefaults = {
        'width': 10,
        'height': 8,
        'scale': 1
    }
    keys_to_rm = ["prefix", "quiet", "postfix", 'libs']
    varname = 'p'

    # process arguments
    prefix = kwargs.get('prefix', '')
    postfix = kwargs.get('postfix', '')
    libs = kwargs.get('libs', [])
    libs = '\n'.join(["library(%s)" % lib for lib in libs])
    quiet = kwargs.get("quiet", False)
    kwargs = {k: v for k, v in kwargs.iteritems()
              if v is not None and k not in keys_to_rm}
    kwdefaults.update(kwargs)
    kwargs = kwdefaults

    # figure out how to load data in the R environment
    if data is None: data = plot.data

    if data is None:
        # Don't load anything, the data source is already present in R
        data_src = ''
    elif isinstance(data, basestring) and 'RPostgreSQL' in data:
        # Hack to allow through data_sql results
        data_src = data
    elif isinstance(data, GGData):
        data_src = str(data)
    else:
        # format the python data object
        data_src = str(data_py(data))

    prog = "%(header)s\n%(libs)s\n%(prefix)s\n%(data)s\n%(postfix)s\n%(varname)s = %(prog)s" % {
        'header': "library(ggplot2)",
        'libs': libs,
        'data': data_src,
        'prefix': prefix,
        'postfix': postfix,
        'varname': varname,
        'prog': plot.r
    }

    if name:
        stmt = GGStatement("ggsave", esc(name), varname, *args, **kwargs)
        prog = "%s\n%s" % (prog, stmt.r)

    if not quiet:
        print prog
        print

    if name:
        execute_r(prog, quiet)
    return prog

Response: Save a GGStatements object to a new name.


Instruction:
Write a Python 3 script for
rendering pygg in an IPython notebook and return a ggplot2 image.

Response:
def gg_ipython(plot, data, width=IPYTHON_IMAGE_SIZE, height=None,
               *args, **kwargs):
    """Render pygg in an IPython notebook

    Allows one to say things like:

    import pygg
    p = pygg.ggplot('diamonds', pygg.aes(x='carat', y='price', color='clarity'))
    p += pygg.geom_point(alpha=0.5, size = 2)
    p += pygg.scale_x_log10(limits=[1, 2])
    pygg.gg_ipython(p, data=None, quiet=True)

    directly in an IPython notebook and see the resulting ggplot2 image
    displayed inline.  This function is print a warning if the IPython library
    cannot be imported.  The ggplot2 image is rendered as a PNG and not
    as a vectorized graphics object right now.

    Note that by default gg_ipython sets the output height and width to
    IPYTHON_IMAGE_SIZE pixels as this is a reasonable default size for a
    browser-based notebook.  Height is by default None, indicating that height
    should be set to the same value as width.  It is possible to adjust
    the aspect ratio of the output by providing non-None values for both
    width and height

    """
    try:
        import IPython.display
        tmp_image_filename = tempfile.NamedTemporaryFile(suffix='.jpg').name
        # Quiet by default
        kwargs['quiet'] = kwargs.get('quiet', True)

        if width is None:
            raise ValueError("Width cannot be None")
        height = height or width
        w_in, h_in = size_r_img_inches(width, height)
        ggsave(name=tmp_image_filename, plot=plot, data=data,
               dpi=600, width=w_in, height=h_in, units=esc('in'),
               *args, **kwargs)
        return IPython.display.Image(filename=tmp_image_filename,
                                     width=width, height=height)
    except ImportError:
        print "Could't load IPython library; integration is disabled"


Instruction:
Implement a function in Python 3 to
compute the width and height for an R image for display in IPython

Response:
def size_r_img_inches(width, height):
    """Compute the width and height for an R image for display in IPython

    Neight width nor height can be null but should be integer pixel values > 0.

    Returns a tuple of (width, height) that should be used by ggsave in R to
    produce an appropriately sized jpeg/png/pdf image with the right aspect
    ratio.  The returned values are in inches.

    """
    # both width and height are given
    aspect_ratio = height / (1.0 * width)
    return R_IMAGE_SIZE, round(aspect_ratio * R_IMAGE_SIZE, 2)


Instruction:
Make a summary of the following Python 3 code
def execute_r(prog, quiet):
    FNULL = open(os.devnull, 'w') if quiet else None
    try:
        input_proc = subprocess.Popen(["echo", prog], stdout=subprocess.PIPE)
        status = subprocess.call("R --no-save --quiet",
                                 stdin=input_proc.stdout,
                                 stdout=FNULL,
                                 stderr=subprocess.STDOUT,
                                 shell=True) # warning, this is a security problem
        if status != 0:
            raise ValueError("ggplot2 bridge failed for program: {}."
                             " Check for an error".format(prog))
    finally:
        if FNULL is not None:
            FNULL.close()

Response: Execute the R code prog an R subprocess and return a list of objects.


Instruction:
How would you explain what the following Python 3 function does
def axis_labels(xtitle,
                ytitle,
                xsuffix="continuous",
                ysuffix="continuous",
                xkwargs={},
                ykwargs={}):
  """
  Helper function to create reasonable axis labels

  @param xtitle String for the title of the X axis.  Automatically escaped
  @param ytitle String for the title of the Y axis.  Automatically escaped
  @param xsuffix Suffix string appended to "scales_x_" to define the type of x axis
                 Default: "continuous"
  @param ysuffix Suffix string appended to "scales_y_" to define the type of y axis
                 Default: "continuous"
  @param xkwargs keyword arguments to pass to scales_x_* function
  @param xkwargs keyword arguments to pass to scales_x_* function
  @return GGStatements

  For example:

      p = ggplot(...)
      p += axis_labels("Dataset Size (MB)",
                       "Latency (sec)",
                       "log10",
                       xkwargs=dict(breaks=[0, 10, 100, 5000]))

  """

  exec "xfunc = scale_x_%s" % xsuffix
  exec "yfunc = scale_y_%s" % ysuffix
  return (
    xfunc(name=esc(xtitle), **xkwargs) +
    yfunc(name=esc(ytitle), **ykwargs)
  )

Response: Returns GGStatements for the basic axis labels.


Instruction:
Can you generate the documentation for the following Python 3 function
def make_master_binding():
  ggplot = make_ggplot2_binding("ggplot")
  def _ggplot(data, *args, **kwargs):
    data_var = data
    if not isinstance(data, basestring):
      data_var = "data"
    else:
      data = None
    stmt = ggplot(data_var, *args, **kwargs)
    stmt.data = data
    return stmt
  return _ggplot

Response:
wrap around ggplot call to handle passed in data objects
 """


Instruction:
Write a Python 3 script to
convert this GGStatement into its R equivalent expression

Response:
def r(self):
        """Convert this GGStatement into its R equivalent expression"""
        r_args = [_to_r(self.args), _to_r(self.kwargs)]
        # remove empty strings from the call args
        r_args = ",".join([x for x in r_args if x != ""])
        return "{}({})".format(self.name, r_args)


Instruction:
Explain what the following Python 3 code does
def encode(precision, with_z):
    logger = logging.getLogger('geobuf')
    stdin = click.get_text_stream('stdin')
    sink = click.get_binary_stream('stdout')
    try:
        data = json.load(stdin)
        pbf = geobuf.encode(
            data,
            precision if precision >= 0 else 6,
            3 if with_z else 2)
        sink.write(pbf)
        sys.exit(0)
    except Exception:
        logger.exception("Failed. Exception caught")
        sys.exit(1)

Response: Given GeoJSON on stdin writes a geobuf file to stdout.


Instruction:
Here you have a function in Python 3, explain what it does
def decode():
    logger = logging.getLogger('geobuf')
    stdin = click.get_binary_stream('stdin')
    sink = click.get_text_stream('stdout')
    try:
        pbf = stdin.read()
        data = geobuf.decode(pbf)
        json.dump(data, sink)
        sys.exit(0)
    except Exception:
        logger.exception("Failed. Exception caught")
        sys.exit(1)

Response:
Given a Geobuf byte string on stdin write a GeoJSON feature
    collection to stdout.


Instruction:
Create a Python 3 function for
encoding an integer into a string preserving order.

Response:
def encode_int(code, bits_per_char=6):
    """Encode int into a string preserving order

    It is using 2, 4 or 6 bits per coding character (default 6).

    Parameters:
        code: int           Positive integer.
        bits_per_char: int  The number of bits per coding character.

    Returns:
        str: the encoded integer
    """
    if code < 0:
        raise ValueError('Only positive ints are allowed!')

    if bits_per_char == 6:
        return _encode_int64(code)
    if bits_per_char == 4:
        return _encode_int16(code)
    if bits_per_char == 2:
        return _encode_int4(code)

    raise ValueError('`bits_per_char` must be in {6, 4, 2}')


Instruction:
Implement a function in Python 3 to
decode string into int assuming encoding with encode_int

Response:
def decode_int(tag, bits_per_char=6):
    """Decode string into int assuming encoding with `encode_int()`

    It is using 2, 4 or 6 bits per coding character (default 6).

    Parameters:
        tag: str           Encoded integer.
        bits_per_char: int  The number of bits per coding character.

    Returns:
        int: the decoded string
    """
    if bits_per_char == 6:
        return _decode_int64(tag)
    if bits_per_char == 4:
        return _decode_int16(tag)
    if bits_per_char == 2:
        return _decode_int4(tag)

    raise ValueError('`bits_per_char` must be in {6, 4, 2}')


Instruction:
Implement a Python 3 function for
encoding a lng lat position as a geohash using a hilbert curve.

Response:
def encode(lng, lat, precision=10, bits_per_char=6):
    """Encode a lng/lat position as a geohash using a hilbert curve

    This function encodes a lng/lat coordinate to a geohash of length `precision`
    on a corresponding a hilbert curve. Each character encodes `bits_per_char` bits
    per character (allowed are 2, 4 and 6 bits [default 6]). Hence, the geohash encodes
    the lng/lat coordinate using `precision` * `bits_per_char` bits. The number of
    bits devided by 2 give the level of the used hilbert curve, e.g. precision=10, bits_per_char=6
    (default values) use 60 bit and a level 30 hilbert curve to map the globe.

    Parameters:
        lng: float          Longitude; between -180.0 and 180.0; WGS 84
        lat: float          Latitude; between -90.0 and 90.0; WGS 84
        precision: int      The number of characters in a geohash
        bits_per_char: int  The number of bits per coding character

    Returns:
        str: geohash for lng/lat of length `precision`
    """
    assert _LNG_INTERVAL[0] <= lng <= _LNG_INTERVAL[1]
    assert _LAT_INTERVAL[0] <= lat <= _LAT_INTERVAL[1]
    assert precision > 0
    assert bits_per_char in (2, 4, 6)

    bits = precision * bits_per_char
    level = bits >> 1
    dim = 1 << level

    x, y = _coord2int(lng, lat, dim)

    if CYTHON_AVAILABLE and bits <= MAX_BITS:
        code = xy2hash_cython(x, y, dim)
    else:
        code = _xy2hash(x, y, dim)

    return encode_int(code, bits_per_char).rjust(precision, '0')


Instruction:
Can you write a function in Python 3 where it
decodes a geohash on a hilbert curve as a lng lat position.

Response:
def decode(code, bits_per_char=6):
    """Decode a geohash on a hilbert curve as a lng/lat position

    Decodes the geohash `code` as a lng/lat position. It assumes, that
    the length of `code` corresponds to the precision! And that each character
    in `code` encodes `bits_per_char` bits. Do not mix geohashes with different
    `bits_per_char`!

    Parameters:
        code: str           The geohash to decode.
        bits_per_char: int  The number of bits per coding character

    Returns:
        Tuple[float, float]:  (lng, lat) coordinate for the geohash.
    """
    assert bits_per_char in (2, 4, 6)

    if len(code) == 0:
        return 0., 0.

    lng, lat, _lng_err, _lat_err = decode_exactly(code, bits_per_char)
    return lng, lat


Instruction:
Make a summary of the following Python 3 code
def decode_exactly(code, bits_per_char=6):
    assert bits_per_char in (2, 4, 6)

    if len(code) == 0:
        return 0., 0., _LNG_INTERVAL[1], _LAT_INTERVAL[1]

    bits = len(code) * bits_per_char
    level = bits >> 1
    dim = 1 << level

    code_int = decode_int(code, bits_per_char)
    if CYTHON_AVAILABLE and bits <= MAX_BITS:
        x, y = hash2xy_cython(code_int, dim)
    else:
        x, y = _hash2xy(code_int, dim)

    lng, lat = _int2coord(x, y, dim)
    lng_err, lat_err = _lvl_error(level)  # level of hilbert curve is bits / 2

    return lng + lng_err, lat + lat_err, lng_err, lat_err

Response: Decodes a geohash on a hilbert curve as a lng lat - error position with error - marginss.


Instruction:
Given the following Python 3 function, write the documentation
def _coord2int(lng, lat, dim):
    assert dim >= 1

    lat_y = (lat + _LAT_INTERVAL[1]) / 180.0 * dim   # [0 ... dim)
    lng_x = (lng + _LNG_INTERVAL[1]) / 360.0 * dim  # [0 ... dim)

    return min(dim - 1, int(floor(lng_x))), min(dim - 1, int(floor(lat_y)))

Response: Convert lon lat values into a dim x dim - grid coordinate system.


Instruction:
Write a Python 3 script to
convert x y values in dim x dim - grid coordinate system into lng lat values.

Response:
def _int2coord(x, y, dim):
    """Convert x, y values in dim x dim-grid coordinate system into lng, lat values.

    Parameters:
        x: int        x value of point [0, dim); corresponds to longitude
        y: int        y value of point [0, dim); corresponds to latitude
        dim: int      Number of coding points each x, y value can take.
                      Corresponds to 2^level of the hilbert curve.

    Returns:
        Tuple[float, float]: (lng, lat)
            lng    longitude value of coordinate [-180.0, 180.0]; corresponds to X axis
            lat    latitude value of coordinate [-90.0, 90.0]; corresponds to Y axis
    """
    assert dim >= 1
    assert x < dim
    assert y < dim

    lng = x / dim * 360 - 180
    lat = y / dim * 180 - 90

    return lng, lat


Instruction:
Write a Python 3 function that can
convert x y value to hashcode.

Response:
def _xy2hash(x, y, dim):
    """Convert (x, y) to hashcode.

    Based on the implementation here:
        https://en.wikipedia.org/w/index.php?title=Hilbert_curve&oldid=797332503

    Pure python implementation.

    Parameters:
        x: int        x value of point [0, dim) in dim x dim coord system
        y: int        y value of point [0, dim) in dim x dim coord system
        dim: int      Number of coding points each x, y value can take.
                      Corresponds to 2^level of the hilbert curve.

    Returns:
        int: hashcode  ∈ [0, dim**2)
    """
    d = 0
    lvl = dim >> 1
    while (lvl > 0):
        rx = int((x & lvl) > 0)
        ry = int((y & lvl) > 0)
        d += lvl * lvl * ((3 * rx) ^ ry)
        x, y = _rotate(lvl, x, y, rx, ry)
        lvl >>= 1
    return d


Instruction:
Can you tell what is the following Python 3 function doing
def _hash2xy(hashcode, dim):
    assert(hashcode <= dim * dim - 1)
    x = y = 0
    lvl = 1
    while (lvl < dim):
        rx = 1 & (hashcode >> 1)
        ry = 1 & (hashcode ^ rx)
        x, y = _rotate(lvl, x, y, rx, ry)
        x += lvl * rx
        y += lvl * ry
        hashcode >>= 2
        lvl <<= 1
    return x, y

Response: Convert a hashcode to x y.


Instruction:
Write a Python 3 function that can
rotate and flip a quadrant appropriately

Response:
def _rotate(n, x, y, rx, ry):
    """Rotate and flip a quadrant appropriately

    Based on the implementation here:
        https://en.wikipedia.org/w/index.php?title=Hilbert_curve&oldid=797332503

    """
    if ry == 0:
        if rx == 1:
            x = n - 1 - x
            y = n - 1 - y
        return y, x
    return x, y


Instruction:
Can you create a Python 3 function that
gets the neighbours of a geohash.

Response:
def neighbours(code, bits_per_char=6):
    """Get the neighbouring geohashes for `code`.

    Look for the north, north-east, east, south-east, south, south-west, west,
    north-west neighbours. If you are at the east/west edge of the grid
    (lng ∈ (-180, 180)), then it wraps around the globe and gets the corresponding
    neighbor.

    Parameters:
        code: str           The geohash at the center.
        bits_per_char: int  The number of bits per coding character.

    Returns:
        dict: geohashes in the neighborhood of `code`. Possible keys are 'north',
            'north-east', 'east', 'south-east', 'south', 'south-west',
            'west', 'north-west'. If the input code covers the north pole, then
            keys 'north', 'north-east', and 'north-west' are not present, and if
            the input code covers the south pole then keys 'south', 'south-west',
            and 'south-east' are not present.
    """
    lng, lat, lng_err, lat_err = decode_exactly(code, bits_per_char)
    precision = len(code)

    north = lat + 2 * lat_err

    south = lat - 2 * lat_err

    east = lng + 2 * lng_err
    if east > 180:
        east -= 360

    west = lng - 2 * lng_err
    if west < -180:
        west += 360

    neighbours_dict = {
        'east': encode(east, lat,   precision, bits_per_char),  # noqa: E241
        'west': encode(west, lat,   precision, bits_per_char),  # noqa: E241
    }

    if north <= 90:  # input cell not already at the north pole
        neighbours_dict.update({
            'north':      encode(lng,  north, precision, bits_per_char),  # noqa: E241
            'north-east': encode(east, north, precision, bits_per_char),  # noqa: E241
            'north-west': encode(west, north, precision, bits_per_char),  # noqa: E241
        })

    if south >= -90:  # input cell not already at the south pole
        neighbours_dict.update({
            'south':      encode(lng,  south, precision, bits_per_char),  # noqa: E241
            'south-east': encode(east, south, precision, bits_per_char),  # noqa: E241
            'south-west': encode(west, south, precision, bits_per_char),  # noqa: E241
        })

    return neighbours_dict


Instruction:
Can you write a function in Python 3 where it
builds a geojson rectangle from code

Response:
def rectangle(code, bits_per_char=6):
    """Builds a (geojson) rectangle from `code`

    The center of the rectangle decodes as the lng/lat for code and
    the rectangle corresponds to the error-margin, i.e. every lng/lat
    point within this rectangle will be encoded as `code`, given `precision == len(code)`.

    Parameters:
        code: str           The geohash for which the rectangle should be build.
        bits_per_char: int  The number of bits per coding character.

    Returns:
        dict: geojson `Feature` containing the rectangle as a `Polygon`.
    """
    lng, lat, lng_err, lat_err = decode_exactly(code, bits_per_char)

    return {
        'type': 'Feature',
        'properties': {
            'code': code,
            'lng': lng,
            'lat': lat,
            'lng_err': lng_err,
            'lat_err': lat_err,
            'bits_per_char': bits_per_char,
        },
        'bbox': (
            lng - lng_err,  # bottom left
            lat - lat_err,
            lng + lng_err,  # top right
            lat + lat_err,
        ),
        'geometry': {
            'type': 'Polygon',
            'coordinates': [[
                (lng - lng_err, lat - lat_err),
                (lng + lng_err, lat - lat_err),
                (lng + lng_err, lat + lat_err),
                (lng - lng_err, lat + lat_err),
                (lng - lng_err, lat - lat_err),
            ]],
        },
    }


Instruction:
Can you generate the documentation for the following Python 3 function
def hilbert_curve(precision, bits_per_char=6):
    bits = precision * bits_per_char

    coords = []
    for i in range(1 << bits):
        code = encode_int(i, bits_per_char).rjust(precision, '0')
        coords += [decode(code, bits_per_char)]

    return {
        'type': 'Feature',
        'properties': {},
        'geometry': {
            'type': 'LineString',
            'coordinates': coords,
        },
    }

Response: Builds the geojson LineString of the used hilbert curve.


Instruction:
Make a summary of the following Python 3 code
def isSignatureValid(expected, received):
    if expected:
        if not received or expected != received:
            return False
    else:
        if received:
            return False
    return True

Response: Verifies that the received signature matches the expected value.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def notifyOnDisconnect(self, callback):
        if self._disconnectCBs is None:
            self._disconnectCBs = []
        self._disconnectCBs.append(callback)

Response: Registers a callback that will be called when the DBus connection to the remote object is lost.


Instruction:
Can you tell what is the following Python 3 function doing
def connectionLost(self, reason):
        if self._disconnectCBs:
            for cb in self._disconnectCBs:
                cb(self, reason)

Response: Called by the DBusObjectHandler when the connection is lost.


Instruction:
Create a Python 3 function for
informing the DBus daemon of the process s interest in the specified signal and registers the callback function to be called when the signal arrives.

Response:
def notifyOnSignal(self, signalName, callback, interface=None):
        """
        Informs the DBus daemon of the process's interest in the specified
        signal and registers the callback function to be called when the
        signal arrives. Multiple callbacks may be registered.

        @type signalName: C{string}
        @param signalName: Name of the signal to register the callback for

        @type callback: Callable object
        @param callback: Callback to be called on signal arrival. The callback
            will be passed signals arguments as positional function arguments.

        @type interface: C{string}
        @param interface: Optional DBus interface emitting the signal. This is
            only needed if more than one interface shares a signal with the
            same name

        @rtype: L{twisted.internet.defer.Deferred}
        @returns: a Deferred to an integer rule_id that may be passed to
            cancelSignalNotification to prevent the delivery of future signals
            to the callback
        """
        iface = None
        signal = None

        for i in self.interfaces:
            if interface and not i.name == interface:
                continue

            if signalName in i.signals:
                signal = i.signals[signalName]
                iface = i
                break

        def callback_caller(sig_msg):
            if isSignatureValid(signal.sig, sig_msg.signature):
                if sig_msg.body:
                    callback(*sig_msg.body)
                else:
                    callback()

        if iface is None:
            raise AttributeError(
                'Requested signal "%s" is not a member of any of the '
                'supported interfaces' % (signalName,),
            )

        d = self.objHandler.conn.addMatch(
            callback_caller,
            mtype='signal',
            path=self.objectPath,
            member=signalName,
            interface=iface.name,
        )

        def on_ok(rule_id):

            if self._signalRules is None:
                self._signalRules = set()

            self._signalRules.add(rule_id)

            return rule_id

        d.addCallback(on_ok)

        return d


Instruction:
Write a Python 3 script to
cancel a callback previously registered with notifyOnSignal

Response:
def cancelSignalNotification(self, rule_id):
        """
        Cancels a callback previously registered with notifyOnSignal
        """
        if self._signalRules and rule_id in self._signalRules:
            self.objHandler.conn.delMatch(rule_id)
            self._signalRules.remove(rule_id)


Instruction:
Create a Python 3 function for
calling the remote method and returns a Deferred instance to the result of the call.

Response:
def callRemote(self, methodName, *args, **kwargs):
        """
        Calls the remote method and returns a Deferred instance to the result.
        DBus does not support passing keyword arguments over the wire. The
        keyword arguments accepted by this method alter the behavior of the
        remote call as described in the kwargs prameter description.

        @type methodName: C{string}
        @param methodName: Name of the method to call

        @param args: Positional arguments to be passed to the remote method

        @param kwargs: Three keyword parameters may be passed to alter the
            behavior of the remote method call. If \"expectReply=False\" is
            supplied, the returned Deferred will be immediately called back
            with the value None. If \"autoStart=False\" is supplied the DBus
            daemon will not attempt to auto-start a service to fulfill the call
            if the service is not yet running (defaults to True). If
            \"timeout=VALUE\" is supplied, the returned Deferred will be
            errbacked with a L{error.TimeOut} instance if the remote call does
            not return before the timeout elapses. If \"interface\" is
            specified, the remote call use the method of the named interface.

        @rtype: L{twisted.internet.defer.Deferred}
        @returns: a Deferred to the result of the remote call
        """
        expectReply = kwargs.get('expectReply', True)
        autoStart = kwargs.get('autoStart', True)
        timeout = kwargs.get('timeout', None)
        interface = kwargs.get('interface', None)

        m = None

        for i in self.interfaces:
            if interface and not interface == i.name:
                continue
            m = i.methods.get(methodName, None)
            if m:
                break

        if m is None:
            raise AttributeError(
                'Requested method "%s" is not a member of any of the '
                'supported interfaces' % (methodName,),
            )

        if len(args) != m.nargs:
            raise TypeError(
                '%s.%s takes %d arguments (%d given)' %
                (i.name, methodName, m.nargs, len(args)),
            )

        return self.objHandler.conn.callRemote(
            self.objectPath, methodName,
            interface=i.name,
            destination=self.busName,
            signature=m.sigIn,
            body=args,
            expectReply=expectReply,
            autoStart=autoStart,
            timeout=timeout,
            returnSignature=m.sigOut,
        )


Instruction:
Can you create a Python 3 function that
calls by the DBus Connection object when the connection is lost.

Response:
def connectionLost(self, reason):
        """
        Called by the DBus Connection object when the connection is lost.

        @type reason: L{twistd.python.failure.Failure}
        @param reason: The value passed to the associated connection's
                       connectionLost method.
        """
        for wref in self._weakProxies.valuerefs():
            p = wref()
            if p is not None:
                p.connectionLost(reason)


Instruction:
Write a Python 3 script to
make the specified object available over DBus

Response:
def exportObject(self, dbusObject):
        """
        Makes the specified object available over DBus

        @type dbusObject: an object implementing the L{IDBusObject} interface
        @param dbusObject: The object to export over DBus
        """
        o = IDBusObject(dbusObject)
        self.exports[o.getObjectPath()] = o
        o.setObjectHandler(self)

        i = {}
        for iface in o.getInterfaces():
            i[iface.name] = o.getAllProperties(iface.name)

        msig = message.SignalMessage(
            o.getObjectPath(),
            'InterfacesAdded',
            'org.freedesktop.DBus.ObjectManager',
            signature='sa{sa{sv}}',
            body=[o.getObjectPath(), i],
        )

        self.conn.sendMessage(msig)


Instruction:
Can you implement a function in Python 3 that
returns a Python dictionary containing the reply content for the managed objects for the specified object path.

Response:
def getManagedObjects(self, objectPath):
        """
        Returns a Python dictionary containing the reply content for
        org.freedesktop.DBus.ObjectManager.GetManagedObjects
        """
        d = {}

        for p in sorted(self.exports.keys()):
            if not p.startswith(objectPath) or p == objectPath:
                continue
            o = self.exports[p]
            i = {}
            d[p] = i
            for iface in o.getInterfaces():
                i[iface.name] = o.getAllProperties(iface.name)

        return d


Instruction:
How would you implement a function in Python 3 that
sends an error message to the local peer.

Response:
def _send_err(self, msg, errName, errMsg):
        """
        Helper method for sending error messages
        """
        r = message.ErrorMessage(
            errName,
            msg.serial,
            body=[errMsg],
            signature='s',
            destination=msg.sender,
        )

        self.conn.sendMessage(r)


Instruction:
Can you generate the documentation for the following Python 3 function
def handleMethodCallMessage(self, msg):
        if (
            msg.interface == 'org.freedesktop.DBus.Peer'
            and msg.member == 'Ping'
        ):
            r = message.MethodReturnMessage(
                msg.serial,
                destination=msg.sender,
            )

            self.conn.sendMessage(r)
            return

        if (
                msg.interface == 'org.freedesktop.DBus.Introspectable'
                and msg.member == 'Introspect'
        ):
            xml = introspection.generateIntrospectionXML(
                msg.path,
                self.exports,
            )

            if xml is not None:
                r = message.MethodReturnMessage(
                    msg.serial,
                    body=[xml],
                    destination=msg.sender,
                    signature='s',
                )

                self.conn.sendMessage(r)

                return

        # Try to get object from complete object path
        o = self.exports.get(msg.path, None)
        if o is None:
            self._send_err(
                msg,
                'org.freedesktop.DBus.Error.UnknownObject',
                '%s is not an object provided by this process.' % (msg.path),
            )
            return

        if (
                msg.interface == 'org.freedesktop.DBus.ObjectManager'
                and msg.member == 'GetManagedObjects'
        ):
            i_and_p = self.getManagedObjects(o.getObjectPath())

            r = message.MethodReturnMessage(
                msg.serial,
                body=[i_and_p],
                destination=msg.sender,
                signature='a{oa{sa{sv}}}',
            )

            self.conn.sendMessage(r)

            return

        i = None

        for x in o.getInterfaces():
            if msg.interface:
                if x.name == msg.interface:
                    i = x
                    break
            else:
                if msg.member in x.methods:
                    i = x
                    break

        m = None
        if i:
            m = i.methods.get(msg.member, None)

        if m is None:
            self._send_err(
                msg,
                'org.freedesktop.DBus.Error.UnknownMethod',
                (
                    'Method "%s" with signature "%s" on interface "%s" '
                    'doesn\'t exist'
                ) % (
                    msg.member, msg.signature or '',
                    msg.interface or '(null)',
                ),
            )

            return

        msig = msg.signature if msg.signature is not None else ''
        esig = m.sigIn if m.sigIn is not None else ''

        if esig != msig:
            self._send_err(
                msg,
                'org.freedesktop.DBus.Error.InvalidArgs',
                'Call to %s has wrong args (%s, expected %s)' %
                (msg.member, msg.signature or '', m.sigIn or '')
            )
            return

        d = defer.maybeDeferred(
            o.executeMethod,
            i,
            msg.member,
            msg.body,
            msg.sender,
        )

        if msg.expectReply:
            def send_reply(return_values):
                if isinstance(return_values, (list, tuple)):
                    if m.nret == 1:
                        return_values = [return_values]
                else:
                    return_values = [return_values]

                r = message.MethodReturnMessage(
                    msg.serial,
                    body=return_values,
                    destination=msg.sender,
                    signature=m.sigOut,
                )
                self.conn.sendMessage(r)

            def send_error(err):
                e = err.value
                errMsg = err.getErrorMessage()
                name = None

                if hasattr(e, 'dbusErrorName'):
                    name = e.dbusErrorName

                if name is None:
                    name = 'org.txdbus.PythonException.' + e.__class__.__name__

                try:
                    marshal.validateErrorName(name)
                except error.MarshallingError:
                    errMsg = ('!!(Invalid error name "%s")!! ' % name) + errMsg
                    name = 'org.txdbus.InvalidErrorName'

                r = message.ErrorMessage(name, msg.serial,
                                         body=[errMsg],
                                         signature='s',
                                         destination=msg.sender)
                self.conn.sendMessage(r)

            d.addCallback(send_reply)
            d.addErrback(send_error)

Response: Handles the DBus MethodCall messages on behalf of the DBus Connection and dispatches them to the appropriate exported object.


Instruction:
Can you tell what is the following Python 3 function doing
def getRemoteObject(self, busName, objectPath, interfaces=None,
                        replaceKnownInterfaces=False):
        """
        Creates a L{RemoteDBusObject} instance to represent the
        specified DBus object.  If explicit interfaces are not
        supplied, DBus object introspection will be used to obtain
        them automatically.

        @type busName: C{string}
        @param busName: Name of the bus exporting the desired object

        @type objectPath: C{string}
        @param objectPath: DBus path of the desired object

        @type interfaces: None, C{string} or L{interface.DBusInterface} or a
                          list of C{string}/L{interface.DBusInterface}
        @param interfaces: May be None, a single value, or a list of string
                           interface names and/or instances of
                           L{interface.DBusInterface}. If None or any of the
                           specified interface names are unknown, full
                           introspection will be attempted.  If interfaces
                           consists of solely of L{interface.DBusInterface}
                           instances and/or known interfacep names, no
                           introspection will be preformed.

        @type replaceKnownInterfaces: C{bool}
        @param replaceKnownInterfaces: If True (defaults to False), any
                                       interfaces discovered during the
                                       introspection process will override any
                                       previous, cached values.

        @rtype: L{twisted.internet.defer.Deferred}
        @returns: A Deferred to the L{RemoteDBusObject} instance
        """

        weak_id = (busName, objectPath, interfaces)

        need_introspection = False
        required_interfaces = set()

        if interfaces is not None:

            ifl = []

            if not isinstance(interfaces, list):
                interfaces = [interfaces]

            for i in interfaces:
                if isinstance(i, interface.DBusInterface):
                    ifl.append(i)
                    required_interfaces.add(i.name)
                else:
                    required_interfaces.add(i)
                    if i in interface.DBusInterface.knownInterfaces:
                        ifl.append(interface.DBusInterface.knownInterfaces[i])
                    else:
                        need_introspection = True

            if not need_introspection:
                return defer.succeed(
                    RemoteDBusObject(self, busName, objectPath, ifl)
                )

        d = self.conn.introspectRemoteObject(
            busName,
            objectPath,
            replaceKnownInterfaces,
        )

        def ok(ifaces):
            missing = required_interfaces - {q.name for q in ifaces}

            if missing:
                raise error.IntrospectionFailed(
                    'Introspection failed to find interfaces: '
                    + ','.join(missing)
                )

            prox = RemoteDBusObject(self, busName, objectPath, ifaces)

            self._weakProxies[weak_id] = prox

            return prox

        d.addCallback(ok)

        return d

Response: Creates a Deferred to obtain the remote object for the specified object path and interfaces.


Instruction:
Implement a function in Python 3 to
add a L{Method m to the interface

Response:
def addMethod(self, m):
        """
        Adds a L{Method} to the interface
        """
        if m.nargs == -1:
            m.nargs = len([a for a in marshal.genCompleteTypes(m.sigIn)])
            m.nret = len([a for a in marshal.genCompleteTypes(m.sigOut)])
        self.methods[m.name] = m
        self._xml = None


Instruction:
Explain what the following Python 3 code does
def addSignal(self, s):
        if s.nargs == -1:
            s.nargs = len([a for a in marshal.genCompleteTypes(s.sig)])
        self.signals[s.name] = s
        self._xml = None

Response: Adds a L{Signal s to the interface


Instruction:
Explain what the following Python 3 code does
def connect(reactor, busAddress='session'):
    from txdbus import endpoints

    f = DBusClientFactory()

    d = f.getConnection()

    eplist = endpoints.getDBusEndpoints(reactor, busAddress)

    eplist.reverse()

    def try_next_ep(err):
        if eplist:
            eplist.pop().connect(f).addErrback(try_next_ep)
        else:
            d.errback(
                ConnectError(
                    string=(
                        'Failed to connect to any bus address. Last error: '
                        + err.getErrorMessage()
                    )
                )
            )

    if eplist:
        try_next_ep(None)
    else:
        d.errback(
            ConnectError(
                string=(
                    'Failed to connect to any bus address. No valid bus '
                    'addresses found'
                )
            )
        )

    return d

Response:
Connect to the specified bus and returns a Deferred to the fully - connected
   .


Instruction:
Implement a Python 3 function for
calling by DBus when the connection has been established.

Response:
def connectionAuthenticated(self):
        """
        Called by L{protocol.BasicDBusProtocol} when the DBus authentication
        has completed successfully.
        """
        self.router = router.MessageRouter()
        self.match_rules = {}
        self.objHandler = objects.DBusObjectHandler(self)
        # serial_number => (deferred, delayed_timeout_cb | None):
        self._pendingCalls = {}
        self._dcCallbacks = []

        d = self.callRemote(
            '/Hello',
            'Hello',
            interface='org.freedesktop.DBus',
            destination='org.freedesktop.DBus',
        )

        d.addCallbacks(
            self._cbGotHello,
            lambda err: self.factory._failed(err),
        )


Instruction:
How would you code a function in Python 3 to
call when the transport loses a connection to the bus.

Response:
def connectionLost(self, reason):
        """
        Called when the transport loses connection to the bus
        """
        if self.busName is None:
            return

        for cb in self._dcCallbacks:
            cb(self, reason)

        for d, timeout in self._pendingCalls.values():
            if timeout:
                timeout.cancel()
            d.errback(reason)
        self._pendingCalls = {}

        self.objHandler.connectionLost(reason)


Instruction:
Explain what the following Python 3 code does
def getRemoteObject(self, busName, objectPath, interfaces=None,
                        replaceKnownInterfaces=False):
        """
        Creates a L{objects.RemoteDBusObject} instance to represent the
        specified DBus object.  If explicit interfaces are not supplied, DBus
        object introspection will be used to obtain them automatically.

        @param interfaces: May be None, a single value, or a list of string
                           interface names and/or instances of
                           L{interface.DBusInterface}. If None or any of the
                           specified interface names are unknown, full
                           introspection will be attempted.  If interfaces
                           consists of solely of L{interface.DBusInterface}
                           instances and/or known interface names, no
                           introspection will be preformed.

        @rtype: L{twisted.internet.defer.Deferred}
        @returns: A deferred to a L{objects.RemoteDBusObject} instance
            representing the remote object
        """
        return self.objHandler.getRemoteObject(
            busName,
            objectPath,
            interfaces,
            replaceKnownInterfaces,
        )

Response: Returns a Deferred that resolves when the remote object is created.


Instruction:
Implement a function in Python 3 to
remove a message matching rule previously registered with addMatch

Response:
def delMatch(self, rule_id):
        """
        Removes a message matching rule previously registered with addMatch
        """
        rule = self.match_rules[rule_id]

        d = self.callRemote(
            '/org/freedesktop/DBus',
            'RemoveMatch',
            interface='org.freedesktop.DBus',
            destination='org.freedesktop.DBus',
            body=[rule],
            signature='s',
        )

        def ok(_):
            del self.match_rules[rule_id]
            self.router.delMatch(rule_id)

        d.addCallback(ok)

        return d


Instruction:
Can you tell what is the following Python 3 function doing
def addMatch(self, callback, mtype=None, sender=None, interface=None,
                 member=None, path=None, path_namespace=None, destination=None,
                 arg=None, arg_path=None, arg0namespace=None):
        """
        Creates a message matching rule, associates it with the specified
        callback function, and sends the match rule to the DBus daemon.
        The arguments to this function are exactly follow the DBus
        specification.  Refer to the \"Message Bus Message Routing\" section of
        the DBus specification for details.

        @rtype: C{int}
        @returns: a L{Deferred} to an integer id that may be used to unregister
            the match rule
        """

        l = []

        def add(k, v):
            if v is not None:
                l.append("%s='%s'" % (k, v))

        add('type', mtype)
        add('sender', sender)
        add('interface', interface)
        add('member', member)
        add('path', path)
        add('path_namespace', path_namespace)
        add('destination', destination)

        if arg:
            for idx, v in arg:
                add('arg%d' % (idx,), v)

        if arg_path:
            for idx, v in arg_path:
                add('arg%dpath' % (idx,), v)

        add('arg0namespace', arg0namespace)

        rule = ','.join(l)

        d = self.callRemote(
            '/org/freedesktop/DBus',
            'AddMatch',
            interface='org.freedesktop.DBus',
            destination='org.freedesktop.DBus',
            body=[rule],
            signature='s',
        )

        def ok(_):
            rule_id = self.router.addMatch(
                callback,
                mtype,
                sender,
                interface,
                member,
                path,
                path_namespace,
                destination,
                arg,
                arg_path,
                arg0namespace,
            )
            self.match_rules[rule_id] = rule
            return rule_id

        d.addCallbacks(ok)

        return d

Response: Adds a new match rule to the specified DBus object.


Instruction:
Given the following Python 3 function, write the documentation
def getNameOwner(self, busName):
        d = self.callRemote(
            '/org/freedesktop/DBus',
            'GetNameOwner',
            interface='org.freedesktop.DBus',
            signature='s',
            body=[busName],
            destination='org.freedesktop.DBus',
        )
        return d

Response: Returns a Deferred to the unique connection name owning the bus name.


Instruction:
Can you tell what is the following Python 3 function doing
def requestBusName(self, newName,
                       allowReplacement=False,
                       replaceExisting=False,
                       doNotQueue=True,
                       errbackUnlessAcquired=True):
        """
        Calls org.freedesktop.DBus.RequestName to request that the specified
        bus name be associated with the connection.

        @type newName: C{string}
        @param newName: Bus name to acquire

        @type allowReplacement: C{bool}
        @param allowReplacement: If True (defaults to False) and another
            application later requests this same name, the new requester will
            be given the name and this connection will lose ownership.

        @type replaceExisting: C{bool}
        @param replaceExisting: If True (defaults to False) and another
            application owns the name but specified allowReplacement at the
            time of the name acquisition, this connection will assume ownership
            of the bus name.

        @type doNotQueue: C{bool}
        @param doNotQueue: If True (defaults to True) the name request will
            fail if the name is currently in use. If False, the request will
            cause this connection to be queued for ownership of the requested
            name

        @type errbackUnlessAcquired: C{bool}
        @param errbackUnlessAcquired: If True (defaults to True) an
            L{twisted.python.failure.Failure} will be returned if the name is
            not acquired.

        @rtype: L{twisted.internet.defer.Deferred}
        @returns: a Deferred to
        """
        flags = 0
        if allowReplacement:
            flags |= 0x1
        if replaceExisting:
            flags |= 0x2
        if doNotQueue:
            flags |= 0x4

        d = self.callRemote(
            '/org/freedesktop/DBus',
            'RequestName',
            interface='org.freedesktop.DBus',
            signature='su',
            body=[newName, flags],
            destination='org.freedesktop.DBus',
        )

        def on_result(r):
            if errbackUnlessAcquired and not (
                    r == NAME_ACQUIRED or r == NAME_ALREADY_OWNER):
                raise error.FailedToAcquireName(newName, r)
            return r

        d.addCallback(on_result)

        return d

Response: Requests that the specified name be associated with the specified connection.


Instruction:
Explain what the following Python 3 code does
def introspectRemoteObject(self, busName, objectPath,
                               replaceKnownInterfaces=False):
        """
        Calls org.freedesktop.DBus.Introspectable.Introspect

        @type busName: C{string}
        @param busName: Name of the bus containing the object

        @type objectPath: C{string}
        @param objectPath: Object Path to introspect

        @type replaceKnownInterfaces: C{bool}
        @param replaceKnownInterfaces: If True (defaults to False), the content
            of the introspected XML will override any pre-existing definitions
            of the contained interfaces.

        @rtype: L{twisted.internet.defer.Deferred}
        @returns: a Deferred to a list of L{interface.DBusInterface} instances
            created from the content of the introspected XML description of the
            object's interface.
        """
        d = self.callRemote(
            objectPath,
            'Introspect',
            interface='org.freedesktop.DBus.Introspectable',
            destination=busName,
        )

        def ok(xml_str):
            return introspection.getInterfacesFromXML(
                xml_str,
                replaceKnownInterfaces
            )

        def err(e):
            raise error.IntrospectionFailed(
                'Introspection Failed: ' + e.getErrorMessage()
            )

        d.addCallbacks(ok, err)

        return d

Response: Introspects the content of the object at the specified path and returns a Deferred to list of DBusInterface instances.


Instruction:
Can you tell what is the following Python 3 function doing
def _cbCvtReply(self, msg, returnSignature):
        if msg is None:
            return None

        if returnSignature != _NO_CHECK_RETURN:
            if not returnSignature:
                if msg.signature:
                    raise error.RemoteError(
                        'Unexpected return value signature')
            else:
                if not msg.signature or msg.signature != returnSignature:
                    msg = 'Expected "%s". Received "%s"' % (
                        str(returnSignature), str(msg.signature))
                    raise error.RemoteError(
                        'Unexpected return value signature: %s' %
                        (msg,))

        if msg.body is None or len(msg.body) == 0:
            return None

        # if not (
        #     isinstance(msg.body[0], six.string_types) and
        #     msg.body[0].startswith('<!D')
        # ):
        #     print('RET SIG', msg.signature, 'BODY:', msg.body)
        if len(msg.body) == 1 and not msg.signature[0] == '(':
            return msg.body[0]
        else:
            return msg.body

Response:
Convert a remote method call reply message into an appropriate callback
        value.


Instruction:
Implement a function in Python 3 to
call a method on a remote DBus object and returns a deferred to the result. @type objectPath: C{string} @param objectPath: Path of the remote object @type methodName: C{string} @param methodName: Name of the method to call @type interface: None or C{string} @param interface: If specified, this specifies the interface containing the desired method @type destination: None or C{string} @param destination: If specified, this specifies the bus name containing the remote object @type signature: None or C{string} @param signature: If specified, this specifies the DBus signature of the body of the DBus MethodCall message. This string must be a valid Signature string as defined by the DBus specification. If arguments are supplied to the method call, this parameter must be provided. @type body: C{list} @param body: A C{list} of Python objects to encode. The list content must match the content of the signature parameter @type expectReply: C{bool} @param expectReply: If True (defaults to True) the returned deferred will be called back with the eventual result of the remote call. If False, the deferred will be immediately called back with None. @type autoStart: C{bool} @param autoStart: If True (defaults to True) DBus will attempt to automatically start a service to handle the method call if a service matching the target object is registered but not yet started. @type timeout: None or C{float} @param timeout: If specified and the remote call does not return a value before the timeout expires, the returned Deferred will be errbacked with a L{error.TimeOut} instance. @type returnSignature: C{string} @param returnSignature: If specified, the return values will be validated against the signature string. If the returned values do not mactch, the returned Deferred witl be errbacked with a L{error.RemoteError} instance. @rtype: L{twisted.internet.defer.Deferred} @returns: a Deferred to the result. If expectReply is False, the deferred will be immediately called back with None.

Response:
def callRemote(self, objectPath, methodName,
                   interface=None,
                   destination=None,
                   signature=None,
                   body=None,
                   expectReply=True,
                   autoStart=True,
                   timeout=None,
                   returnSignature=_NO_CHECK_RETURN):
        """
        Calls a method on a remote DBus object and returns a deferred to the
        result.

        @type objectPath: C{string}
        @param objectPath: Path of the remote object

        @type methodName: C{string}
        @param methodName: Name of the method to call

        @type interface: None or C{string}
        @param interface: If specified, this specifies the interface containing
            the desired method

        @type destination: None or C{string}
        @param destination: If specified, this specifies the bus name
        containing the remote object

        @type signature: None or C{string}
        @param signature: If specified, this specifies the DBus signature of
            the body of the DBus MethodCall message. This string must be a
            valid Signature string as defined by the DBus specification. If
            arguments are supplied to the method call, this parameter must be
            provided.

        @type body: C{list}
        @param body: A C{list} of Python objects to encode. The list content
            must match the content of the signature parameter

        @type expectReply: C{bool}
        @param expectReply: If True (defaults to True) the returned deferred
            will be called back with the eventual result of the remote call. If
            False, the deferred will be immediately called back with None.

        @type autoStart: C{bool}
        @param autoStart: If True (defaults to True) DBus will attempt to
            automatically start a service to handle the method call if a
            service matching the target object is registered but not yet
            started.

        @type timeout: None or C{float}
        @param timeout: If specified and the remote call does not return a
            value before the timeout expires, the returned Deferred will be
            errbacked with a L{error.TimeOut} instance.

        @type returnSignature: C{string}
        @param returnSignature: If specified, the return values will be
            validated against the signature string. If the returned values do
            not mactch, the returned Deferred witl be errbacked with a
            L{error.RemoteError} instance.

        @rtype: L{twisted.internet.defer.Deferred}
        @returns: a Deferred to the result. If expectReply is False, the
             deferred will be immediately called back with None.
        """

        try:
            mcall = message.MethodCallMessage(
                objectPath,
                methodName,
                interface=interface,
                destination=destination,
                signature=signature,
                body=body,
                expectReply=expectReply,
                autoStart=autoStart,
                oobFDs=self._toBeSentFDs,
            )

            d = self.callRemoteMessage(mcall, timeout)

            d.addCallback(self._cbCvtReply, returnSignature)

            return d
        except Exception:
            return defer.fail()


Instruction:
Write a Python 3 function that can
call when a remote method invocation timeout occurs.

Response:
def _onMethodTimeout(self, serial, d):
        """
        Called when a remote method invocation timeout occurs
        """
        del self._pendingCalls[serial]
        d.errback(error.TimeOut('Method call timed out'))


Instruction:
How would you explain what the following Python 3 function does
def callRemoteMessage(self, mcall, timeout=None):
        assert isinstance(mcall, message.MethodCallMessage)

        if mcall.expectReply:
            d = defer.Deferred()

            if timeout:
                timeout = reactor.callLater(
                    timeout, self._onMethodTimeout, mcall.serial, d)

            self._pendingCalls[mcall.serial] = (d, timeout)

            self.sendMessage(mcall)

            return d
        else:
            self.sendMessage(mcall)

            return defer.succeed(None)

Response: Sends a remote method call to the remote method.


Instruction:
Write a Python 3 script for
calling when a method return message is received.

Response:
def methodReturnReceived(self, mret):
        """
        Called when a method return message is received
        """
        d, timeout = self._pendingCalls.get(mret.reply_serial, (None, None))
        if timeout:
            timeout.cancel()
        if d:
            del self._pendingCalls[mret.reply_serial]
            d.callback(mret)


Instruction:
Can you generate the documentation for the following Python 3 function
def errorReceived(self, merr):
        d, timeout = self._pendingCalls.get(merr.reply_serial, (None, None))
        if timeout:
            timeout.cancel()
        if d:
            del self._pendingCalls[merr.reply_serial]
            e = error.RemoteError(merr.error_name)
            e.message = ''
            e.values = []
            if merr.body:
                if isinstance(merr.body[0], six.string_types):
                    e.message = merr.body[0]
                e.values = merr.body
            d.errback(e)

Response: Called when an error is received from the broker.


Instruction:
Implement a function in Python 3 to
return a list of endpoints from the DBUS_SESSION_BUS_ADDRESS environment variable.

Response:
def getDBusEnvEndpoints(reactor, client=True):
    """
    Creates endpoints from the DBUS_SESSION_BUS_ADDRESS environment variable

    @rtype: C{list} of L{twisted.internet.interfaces.IStreamServerEndpoint}
    @returns: A list of endpoint instances
    """
    env = os.environ.get('DBUS_SESSION_BUS_ADDRESS', None)
    if env is None:
        raise Exception('DBus Session environment variable not set')

    return getDBusEndpoints(reactor, env, client)


Instruction:
Can you write a function in Python 3 where it
returns a list of DBus endpoints for the given bus address.

Response:
def getDBusEndpoints(reactor, busAddress, client=True):
    """
    Creates DBus endpoints.

    @param busAddress: 'session', 'system', or a valid bus address as defined
        by the DBus specification. If 'session' (the default) or 'system' is
        supplied, the contents of the DBUS_SESSION_BUS_ADDRESS or
        DBUS_SYSTEM_BUS_ADDRESS environment variables will be used for the bus
        address, respectively. If DBUS_SYSTEM_BUS_ADDRESS is not set, the
        well-known address unix:path=/var/run/dbus/system_bus_socket will be
        used.
    @type busAddress: C{string}

    @rtype: C{list} of L{twisted.internet.interfaces.IStreamServerEndpoint}
    @returns: A list of endpoint instances
    """

    if busAddress == 'session':
        addrString = os.environ.get('DBUS_SESSION_BUS_ADDRESS', None)
        if addrString is None:
            raise Exception('DBus Session environment variable not set')

    elif busAddress == 'system':
        addrString = os.environ.get(
            'DBUS_SYSTEM_BUS_ADDRESS',
            'unix:path=/var/run/dbus/system_bus_socket',
        )

    else:
        addrString = busAddress

    # XXX Add documentation about extra key=value parameters in address string
    #    such as nonce-tcp vs tcp which use same endpoint class
    epl = []

    for ep_addr in addrString.split(';'):
        d = {}
        kind = None
        ep = None

        for c in ep_addr.split(','):
            if c.startswith('unix:'):
                kind = 'unix'
                c = c[5:]
            elif c.startswith('tcp:'):
                kind = 'tcp'
                c = c[4:]
            elif c.startswith('nonce-tcp:'):
                kind = 'tcp'
                c = c[10:]
                d['nonce-tcp'] = True
            elif c.startswith('launchd:'):
                kind = 'launchd'
                c = c[7:]

            if '=' in c:
                k, v = c.split('=')
                d[k] = v

        if kind == 'unix':
            if 'path' in d:
                path = d['path']
            elif 'tmpdir' in d:
                path = d['tmpdir'] + '/dbus-' + str(os.getpid())
            elif 'abstract' in d:
                path = '\0' + d['abstract']

            if client:
                ep = UNIXClientEndpoint(reactor, path=path)
            else:
                ep = UNIXServerEndpoint(reactor, address=path)

        elif kind == 'tcp':
            if client:
                ep = TCP4ClientEndpoint(reactor, d['host'], int(d['port']))
            else:
                ep = TCP4ServerEndpoint(reactor, int(
                    d['port']), interface=d['host'])

        if ep:
            ep.dbus_args = d
            epl.append(ep)

    return epl


Instruction:
Implement a Python 3 function for
validating that the provided object path conforms to the DBus standard.

Response:
def validateObjectPath(p):
    """
    Ensures that the provided object path conforms to the DBus standard.
    Throws a L{error.MarshallingError} if non-conformant

    @type p: C{string}
    @param p: A DBus object path
    """
    if not p.startswith('/'):
        raise MarshallingError('Object paths must begin with a "/"')
    if len(p) > 1 and p[-1] == '/':
        raise MarshallingError('Object paths may not end with "/"')
    if '//' in p:
        raise MarshallingError('"//" is not allowed in object paths"')
    if invalid_obj_path_re.search(p):
        raise MarshallingError('Invalid characters contained in object path')


Instruction:
How would you code a function in Python 3 to
validate that the supplied name is a valid DBus Interface name.

Response:
def validateInterfaceName(n):
    """
    Verifies that the supplied name is a valid DBus Interface name. Throws
    an L{error.MarshallingError} if the format is invalid

    @type n: C{string}
    @param n: A DBus interface name
    """
    try:
        if '.' not in n:
            raise Exception('At least two components required')
        if '..' in n:
            raise Exception('".." not allowed in interface names')
        if len(n) > 255:
            raise Exception('Name exceeds maximum length of 255')
        if n[0] == '.':
            raise Exception('Names may not begin with a "."')
        if n[0].isdigit():
            raise Exception('Names may not begin with a digit')
        if if_re.search(n):
            raise Exception(
                'Names contains a character outside the set [A-Za-z0-9_.]')
        if dot_digit_re.search(n):
            raise Exception(
                'No components of an interface name may begin with a digit')
    except Exception as e:
        raise MarshallingError('Invalid interface name "%s": %s' % (n, str(e)))


Instruction:
Write a Python 3 function that can
validate that the supplied name is a valid DBus Bus name.

Response:
def validateBusName(n):
    """
    Verifies that the supplied name is a valid DBus Bus name. Throws
    an L{error.MarshallingError} if the format is invalid

    @type n: C{string}
    @param n: A DBus bus name
    """
    try:
        if '.' not in n:
            raise Exception('At least two components required')
        if '..' in n:
            raise Exception('".." not allowed in bus names')
        if len(n) > 255:
            raise Exception('Name exceeds maximum length of 255')
        if n[0] == '.':
            raise Exception('Names may not begin with a "."')
        if n[0].isdigit():
            raise Exception('Names may not begin with a digit')
        if bus_re.search(n):
            raise Exception(
                'Names contains a character outside the set [A-Za-z0-9_.\\-:]')
        if not n[0] == ':' and dot_digit_re.search(n):
            raise Exception(
                'No coponents of an interface name may begin with a digit')
    except Exception as e:
        raise MarshallingError('Invalid bus name "%s": %s' % (n, str(e)))


Instruction:
Here you have a function in Python 3, explain what it does
def validateMemberName(n):
    try:
        if len(n) < 1:
            raise Exception('Name must be at least one byte in length')
        if len(n) > 255:
            raise Exception('Name exceeds maximum length of 255')
        if n[0].isdigit():
            raise Exception('Names may not begin with a digit')
        if mbr_re.search(n):
            raise Exception(
                'Names contains a character outside the set [A-Za-z0-9_]')
    except Exception as e:
        raise MarshallingError('Invalid member name "%s": %s' % (n, str(e)))

Response: Validates that the supplied name is a valid DBus member name. Throws an exception if the name is invalid.


Instruction:
Here you have a function in Python 3, explain what it does
def dbus_lenFD(self, fd):
        f = os.fdopen(fd, 'rb')
        result = len(f.read())
        f.close()
        return result

Response: Returns the byte count after reading till EOF.


Instruction:
How would you code a function in Python 3 to
read byte_count bytes from fd and returns them.

Response:
def dbus_readBytesFD(self, fd, byte_count):
        """
        Reads byte_count bytes from fd and returns them.
        """
        f = os.fdopen(fd, 'rb')
        result = f.read(byte_count)
        f.close()
        return bytearray(result)


Instruction:
Write a Python 3 script to
read byte_count from fd1 and fd2. Returns concatenation of byte_count.

Response:
def dbus_readBytesTwoFDs(self, fd1, fd2, byte_count):
        """
        Reads byte_count from fd1 and fd2. Returns concatenation.
        """
        result = bytearray()
        for fd in (fd1, fd2):
            f = os.fdopen(fd, 'rb')
            result.extend(f.read(byte_count))
            f.close()
        return result


Instruction:
How would you explain what the following Python 3 function does
def generateIntrospectionXML(objectPath, exportedObjects):
    l = [_dtd_decl]
    l.append('<node name="%s">' % (objectPath,))

    obj = exportedObjects.get(objectPath, None)
    if obj is not None:
        for i in obj.getInterfaces():
            l.append(i.introspectionXml)
        l.append(_intro)

    # make sure objectPath ends with '/' to only get partial matches based on
    # the full path, not a part of a subpath
    if not objectPath.endswith('/'):
        objectPath += '/'
    matches = []
    for path in exportedObjects.keys():
        if path.startswith(objectPath):
            path = path[len(objectPath):].partition('/')[0]
            if path not in matches:
                matches.append(path)

    if obj is None and not matches:
        return None

    for m in matches:
        l.append('<node name="%s"/>' % m)

    l.append('</node>')
    return '\n'.join(l)

Response: Generates the introspection XML for an object path or partial object path.


Instruction:
Can you write a function in Python 3 where it
parses the supplied Introspection XML string and returns a list of L { interface. DBusInerface } instances representing the XML interface that is defined within the XML string.

Response:
def getInterfacesFromXML(xmlStr, replaceKnownInterfaces=False):
    """
    Parses the supplied Introspection XML string and returns a list of
    L{interface.DBusInerface} instances representing the XML interface
    definitions.

    @type replaceKnownInterfaces: C{bool}
    @param replaceKnownInterfaces: If true, pre-existing interface definitions
                                   will be replaced by the contents of the
                                   interfaces defined within the XML string

    @rtype: C{list} of L{interface.DBusInerface}
    """
    handler = IntrospectionHandler(replaceKnownInterfaces)

    xmlStr = xmlStr.strip()
    if xmlStr.startswith('<!DOCTYPE'):
        xmlStr = xmlStr[xmlStr.find('>') + 1:]

    # xml.sax.parseString( xmlStr, handler )
    p = xml.sax.make_parser()
    p.setFeature(xml.sax.handler.feature_validation, False)
    p.setFeature(xml.sax.handler.feature_external_ges, False)
    p.setContentHandler(handler)
    p.parse(cStringIO(xmlStr))

    return handler.interfaces


Instruction:
Write a Python 3 script for
calling when a client connects to the bus. This method assigns the unique name of the client to the bus and adds the client to the list of clients that are connected to the bus.

Response:
def clientConnected(self, proto):
        """
        Called when a client connects to the bus. This method assigns the
        new connection a unique bus name.
        """
        proto.uniqueName = ':1.%d' % (self.next_id,)
        self.next_id += 1
        self.clients[proto.uniqueName] = proto


Instruction:
Can you generate the documentation for the following Python 3 function
def clientDisconnected(self, proto):
        for rule_id in proto.matchRules:
            self.router.delMatch(rule_id)

        for busName in proto.busNames.keys():
            self.dbus_ReleaseName(busName, proto.uniqueName)

        if proto.uniqueName:
            del self.clients[proto.uniqueName]

Response: Called when a client disconnects from the bus