Instruction:
How would you explain what the following Python 3 function does
def filter(self, cls_or_collection, query, raw = False,only = None,include = None):

        if not isinstance(cls_or_collection, six.string_types):
            collection = self.get_collection_for_cls(cls_or_collection)
            cls = cls_or_collection
        else:
            collection = cls_or_collection
            cls = self.get_cls_for_collection(collection)

        table = self._collection_tables[collection]

        joins = defaultdict(dict)
        joins_list = []
        group_bys = []
        havings = []

        def compile_query(collection,query,table = None,path = None):
            if path is None:
                path = []

            """
            This function emits a list of WHERE statements that can be used to retrieve
            """

            if table is None:
                table = self._collection_tables[collection]

            where_statements  = []

            if any([True if key.startswith('$') else False for key in query.keys()]):
                #this is a special operator query
                if len(query) > 1:
                    raise AttributeError('Currently not supported!')
                operator = list(query.keys())[0][1:]
                if not operator in ('and','or','not'):
                    raise AttributeError("Non-supported logical operator: $%s" % operator)
                if operator in ('and','or'):
                    where_statements = [sq for expr in query['$%s' % operator]
                                        for sq in compile_query(collection,expr,path = path)]
                    if operator == 'and':
                        return [and_(*where_statements)]
                    else:
                        return [or_(*where_statements)]
                elif operator  == 'not':
                    return [not_(*compile_query(collection,query['$not'],table = table,path = path))]

            def compile_one_to_many_query(key,query,field_name,related_table,count_column,path):

                def prepare_subquery(tail,query_dict):
                    d = {}
                    if not tail:
                        if isinstance(query_dict,dict):
                            return query_dict.copy()
                        if not isinstance(query_dict,Document):
                            raise AttributeError("Must be a document!")
                        if not query_dict.pk:
                            raise AttributeError("Performing a query without a primary key!")
                        return {'pk' : query_dict.pk}
                    return {tail : query_dict}

                tail = key[len(field_name)+1:]

                if isinstance(query,Document) and not tail:
                    query = {'pk' : query.pk}

                #to do: implement $size and $not: {$size} operators...
                if isinstance(query,dict) and len(query) == 1 and list(query.keys())[0] in ('$all','$in','$elemMatch','$nin'):
                    #this is an $in/$all/$nin query
                    query_type = list(query.keys())[0][1:]
                    subquery = list(query.values())[0]

                    if query_type == 'elemMatch':
                        queries = compile_query(params['collection'],
                                                prepare_subquery(tail,query['$elemMatch']),
                                                table = related_table,
                                                path = path)
                        return queries
                    else:
                        if isinstance(subquery,(ManyToManyProxy,QuerySet)):
                            if tail:
                                #this query has a tail
                                query = {tail : query}
                                queries = compile_query(params['collection'],query,
                                                table = related_table,
                                                path = path)
                                return queries
                            #this is a query with a ManyToManyProxy/QuerySet
                            if isinstance(subquery,ManyToManyProxy):
                                qs = subquery.get_queryset()
                            else:
                                qs = subquery
                            if not query_type in ('in','nin','all'):
                                raise AttributeError
                            if query_type == 'all':
                                op = 'in'
                            else:
                                op = query_type
                            if query_type == 'all':
                                cnt = func.count(count_column)
                                condition = cnt == qs.get_count_select()
                                havings.append(condition)
                            return [getattr(related_table.c['pk'],op+'_')(qs.get_select(columns = ['pk']))]
                        elif isinstance(subquery,(list,tuple)):
                            if subquery and isinstance(subquery[0],dict) and len(subquery[0]) == 1 and \
                            list(subquery[0].keys())[0] == '$elemMatch':
                                queries = [sq for v in subquery for sq in compile_query(params['collection'],
                                                                                prepare_subquery(tail,v['$elemMatch']),
                                                                                table = related_table,
                                                                                path = path)]
                            else:
                                queries = [sq for v in subquery for sq in compile_query(params['collection'],
                                                                                prepare_subquery(tail,v),
                                                                                table = related_table,
                                                                                path = path)]
                            where_statement = or_(*queries)

                            if query_type == 'nin':
                                where_statement = not_(where_statement)

                            if query_type == 'all' and len(queries) > 1:
                                cnt = func.count(count_column)
                                havings.append(cnt == len(queries))

                            return [where_statement]
                        else:
                            raise AttributeError("$in/$nin/$all query requires a list/tuple/QuerySet/ManyToManyProxy")
                else:
                    return compile_query(params['collection'],prepare_subquery(tail,query),
                                    table = related_table,
                                    path = path)

            def compile_many_to_many_query(key,value,field_name,params,relationship_table,path):

                related_collection = params['collection']
                related_table = self._collection_tables[related_collection]

                path_str = ".".join(path)

                if path_str in joins[relationship_table]:
                    relationship_table_alias = joins[relationship_table][path_str]
                else:
                    relationship_table_alias = relationship_table.alias()
                    joins[relationship_table][path_str] = relationship_table_alias
                    joins_list.append((relationship_table_alias,
                                       relationship_table_alias.c[params['pk_field_name']] == table.c['pk']))

                if path_str in joins[related_table]:
                    related_table_alias = joins[related_table][path_str]
                else:
                    related_table_alias = related_table.alias()
                    joins[related_table][path_str] = related_table_alias
                    joins_list.append((related_table_alias,relationship_table_alias.c[params['related_pk_field_name']] == related_table_alias.c['pk']))

                return compile_one_to_many_query(key,value,field_name,related_table_alias,relationship_table_alias.c[params['pk_field_name']],new_path)

            def prepare_special_query(field_name,params,query):
                def sanitize(value):
                    if isinstance(value,(list,tuple)):
                        return [v.pk if isinstance(v,Document) else v for v in value]
                    return value
                column_name = params['column']
                if '$not' in query:
                    return [not_(*prepare_special_query(column_name,params,sanitize(query['$not'])))]
                elif '$in' in query:
                    if not query['$in']:
                        #we return an impossible condition since the $in query does not contain any values
                        return [expression.cast(True,Boolean) == expression.cast(False,Boolean)]
                    return [table.c[column_name].in_(sanitize(query['$in']))]
                elif '$nin' in query:
                    if not query['$nin']:
                        return [expression.cast(True,Boolean) == expression.cast(False,Boolean)]
                    return [~table.c[column_name].in_(sanitize(query['$nin']))]
                elif '$eq' in query:
                    return [table.c[column_name] == sanitize(query['$eq'])]
                elif '$ne' in query:
                    return [table.c[column_name] != sanitize(query['$ne'])]
                elif '$gt' in query:
                    return [table.c[column_name] > sanitize(query['$gt'])]
                elif '$gte' in query:
                    return [table.c[column_name] >= sanitize(query['$gte'])]
                elif '$lt' in query:
                    return [table.c[column_name] < sanitize(query['$lt'])]
                elif '$lte' in query:
                    return [table.c[column_name] <= sanitize(query['$lte'])]
                elif '$exists' in query:
                    if query['$exists']:
                        return [table.c[column_name] != None]
                    else:
                        return [table.c[column_name] == None]
                elif '$like' in query:
                    return [table.c[column_name].like(expression.cast(query['$like'],String))]
                elif '$ilike' in query:
                    return [table.c[column_name].ilike(expression.cast(query['$ilike'],String))]
                elif '$regex' in query:
                    if not self.engine.url.drivername in ('postgres','mysql','sqlite'):
                        raise AttributeError("Regex queries not supported with %s engine!" % self.engine.url.drivername)
                    return [table.c[column_name].op('REGEXP')(expression.cast(query['$regex'],String))]
                else:
                    raise AttributeError("Invalid query!")

            #this is a normal, field-base query
            for key,value in query.items():
                for field_name,params in self._index_fields[collection].items():
                    if key == field_name:
                        if isinstance(value,re._pattern_type):
                            value = {'$regex' : value.pattern}
                        if isinstance(value,dict):
                            #this is a special query
                            where_statements.extend(prepare_special_query(field_name,params,value))
                        else:
                            #this is a normal value query
                            where_statements.append(table.c[params['column']] == expression.cast(value,params['type']))
                        break
                else:
                    #we check the normal relationships
                    for field_name,params in self._related_fields[collection].items():
                        if key.startswith(field_name):

                            head,tail = key[:len(field_name)],key[len(field_name)+1:]
                            new_path = path + [head]
                            path_str = ".".join(new_path)
                            #ManyToManyField
                            if isinstance(params['field'],ManyToManyField):
                                relationship_table = self._relationship_tables[collection][field_name]
                                where_statements.extend(compile_many_to_many_query(key,value,field_name,params,relationship_table,path = new_path))
                            elif isinstance(params['field'],ForeignKeyField):#this is a normal ForeignKey relation
                                if key == field_name:
                                    #this is a ForeignKey query
                                    if isinstance(value,dict):
                                        if len(value) == 1:
                                            key,query = list(value.items())[0]
                                            if key == '$exists':
                                                if not isinstance(query,bool):
                                                    raise AttributeError("$exists operator requires a Boolean operator")
                                                if query:
                                                    where_statements.append(table.c[params['column']] != None)
                                                else:
                                                    where_statements.append(table.c[params['column']] == None)
                                                break
                                            elif not key in ('$in','$nin'):
                                                raise AttributeError("Invalid query!")
                                            query_type = key[1:]
                                        else:
                                            raise AttributeError("Invalid query!")
                                    else:
                                        query_type = 'exact'
                                        query = value
                                    if isinstance(query,(QuerySet,ManyToManyProxy)):
                                        if not query_type in ('in','nin'):
                                            raise AttributeError("QuerySet/ManyToManyProxy objects must be used in conjunction with $in/$nin when querying a ForeignKey relationship")
                                        if isinstance(query,ManyToManyProxy):
                                            qs = query.get_queryset()
                                        else:
                                            qs = query
                                        if qs.count is not None and qs.count == 0:
                                            raise AttributeError("$in/$nin query with empty QuerySet/ManyToManyProxy!")
                                        if qs.cls is not params['class']:
                                            raise AttributeError("Invalid QuerySet class!")
                                        condition = getattr(table.c[params['column']],query_type+'_')(qs.get_select(columns = ['pk']))
                                        where_statements.append(condition)
                                    elif isinstance(query,(list,tuple)):
                                        if not query_type in ('in','nin'):
                                            raise AttributeError("Lists/tuples must be used in conjunction with $in/$nin when querying a ForeignKey relationship")
                                        if not query:
                                            raise AttributeError("in/nin query with empty list!")
                                        if query[0].__class__ is params['class']:
                                            if any((element.__class__ is not params['class'] for element in query)):
                                                raise AttributeError("Invalid document type in ForeignKey query")
                                            where_statements.append(getattr(table.c[params['column']],query_type+'_')([expression.cast(doc.pk,params['type']) for doc in query]))
                                        else:
                                            where_statements.append(getattr(table.c[params['column']],query_type+'_')([expression.cast(element,params['type']) for element in query]))
                                    elif isinstance(query,Document):
                                        #we need an exact clas match here...
                                        if query.__class__ is not params['class']:
                                            raise AttributeError("Invalid Document class!")
                                        where_statements.append(table.c[params['column']] == query.pk)
                                    else:
                                        where_statements.append(table.c[params['column']] == expression.cast(query,params['class'].Meta.PkType))
                                else:
                                    #we query a sub-field of the relation
                                    related_table = self._collection_tables[params['collection']]

                                    if path_str in joins[related_table]:
                                        related_table_alias = joins[related_table][path_str]
                                    else:
                                        related_table_alias = related_table.alias()
                                        joins[related_table][path_str] = related_table_alias
                                        joins_list.append((related_table_alias,table.c[params['column']] == related_table_alias.c['pk']))
                                    where_statements.extend(compile_query(params['collection'],{tail : value},table = related_table_alias,path = new_path))
                            elif isinstance(params['field'],OneToManyField):
                                related_table = self._collection_tables[params['collection']]

                                if path_str in joins[related_table]:
                                    related_table_alias = joins[related_table][path_str]
                                else:
                                    related_table_alias = related_table.alias()
                                    joins[related_table][path_str] = related_table_alias
                                    joins_list.append((related_table_alias,related_table_alias.c[params['backref']['column']] == table.c['pk']))

                                where_statements.extend(compile_one_to_many_query(key,value,field_name,related_table_alias,table.c.pk,new_path))
                            break
                    else:
                        raise AttributeError("Query over non-indexed field %s in collection %s!" % (key,collection))
            return where_statements

        compiled_query = compile_query(collection,query)

        if len(compiled_query) > 1:
            compiled_query = and_(*compiled_query)
        elif compiled_query:
            compiled_query = compiled_query[0]
        else:
            compiled_query = None

        return QuerySet(backend = self, table = table,
                        joins = joins_list,
                        cls = cls,
                        condition = compiled_query,
                        raw = raw,
                        group_bys = group_bys,
                        only = only,
                        include = include,
                        havings = havings
                        )

Response: This method returns a list of objects that correspond to a given set of properties.


Instruction:
How would you implement a function in Python 3 that
transforms the query dictionary to replace e. g. documents with __ref__ fields.

Response:
def _canonicalize_query(self, query):

        """
        Transform the query dictionary to replace e.g. documents with __ref__ fields.
        """

        def transform_query(q):

            for encoder in self.query_encoders:
                q = encoder.encode(q,[])

            if isinstance(q, dict):
                nq = {}
                for key,value in q.items():
                    new_key = key
                    if isinstance(value,dict) and len(value) == 1 and list(value.keys())[0].startswith('$'):
                        if list(value.keys())[0] in ('$all','$in'):
                            if list(value.values())[0] and isinstance(list(value.values())[0][0],Document):
                                if self._use_pk_based_refs:
                                    new_key+='.pk'
                                else:
                                    new_key+='.__ref__'
                    elif isinstance(value,Document):
                        if self._use_pk_based_refs:
                            new_key+='.pk'
                        else:
                            new_key+='.__ref__'
                    nq[new_key] = transform_query(value)
                return nq
            elif isinstance(q, (list,QuerySet,tuple)):
                return [transform_query(x) for x in q]
            elif isinstance(q,Document):
                collection = self.get_collection_for_obj(q)
                if self._use_pk_based_refs:
                    return q.pk
                else:
                    return "%s:%s" % (collection,q.pk)
            else:
                return q

        return transform_query(query)


Instruction:
Write a Python 3 script to
filter objects from the database that correspond to a given set of properties.

Response:
def filter(self, cls_or_collection, query, raw=False, only=None):
        """
        Filter objects from the database that correspond to a given set of properties.

        See :py:meth:`blitzdb.backends.base.Backend.filter` for documentation of individual parameters

        .. note::

            This function supports most query operators that are available in MongoDB and returns
            a query set that is based on a MongoDB cursor.

        """

        if not isinstance(cls_or_collection, six.string_types):
            collection = self.get_collection_for_cls(cls_or_collection)
            cls = cls_or_collection
        else:
            collection = cls_or_collection
            cls = self.get_cls_for_collection(collection)

        canonical_query = self._canonicalize_query(query)

        args = {}

        if only:
            if isinstance(only,tuple):
                args['projection'] = list(only)
            else:
                args['projection'] = only

        return QuerySet(self, cls, self.db[collection].find(canonical_query, **args), raw=raw, only=only)


Instruction:
Write a Python 3 function for
generating boolean operator checking function.

Response:
def boolean_operator_query(boolean_operator):
    """Generate boolean operator checking function."""
    def _boolean_operator_query(expressions):
        """Apply boolean operator to expressions."""
        def _apply_boolean_operator(query_function, expressions=expressions):
            """Return if expressions with boolean operator are satisfied."""
            compiled_expressions = [compile_query(e) for e in expressions]
            return reduce(
                boolean_operator,
                [e(query_function) for e in compiled_expressions]
            )

        return _apply_boolean_operator
    return _boolean_operator_query


Instruction:
Implement a function in Python 3 to
filter documents with a key that satisfies an expression.

Response:
def filter_query(key, expression):
    """Filter documents with a key that satisfies an expression."""
    if (isinstance(expression, dict)
            and len(expression) == 1
            and list(expression.keys())[0].startswith('$')):
        compiled_expression = compile_query(expression)
    elif callable(expression):
        def _filter(index, expression=expression):
            result = [store_key
                      for value, store_keys in index.get_index().items()
                      if expression(value)
                      for store_key in store_keys]
            return result
        compiled_expression = _filter
    else:
        compiled_expression = expression

    def _get(query_function, key=key, expression=compiled_expression):
        """Get document key and check against expression."""
        return query_function(key, expression)

    return _get


Instruction:
Can you generate the documentation for the following Python 3 function
def not_query(expression):
    compiled_expression = compile_query(expression)

    def _not(index, expression=compiled_expression):
        """Return store key for documents that satisfy expression."""
        all_keys = index.get_all_keys()
        returned_keys = expression(index)
        return [key for key in all_keys if key not in returned_keys]

    return _not

Response: Return a function that returns the store keys that satisfy the given logical not expression.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def comparison_operator_query(comparison_operator):
    def _comparison_operator_query(expression):
        """Apply binary operator to expression."""
        def _apply_comparison_operator(index, expression=expression):
            """Return store key for documents that satisfy expression."""
            ev = expression() if callable(expression) else expression
            return [
                store_key
                for value, store_keys
                in index.get_index().items()
                if comparison_operator(value, ev)
                for store_key in store_keys
            ]
        return _apply_comparison_operator
    return _comparison_operator_query

Response: Generates a comparison operator checking function that returns a list of store keys that satisfy the given binary operator.


Instruction:
Write a Python 3 script to
return a function that checks that documents have a key that satisfies expression.

Response:
def exists_query(expression):
    """Check that documents have a key that satisfies expression."""
    def _exists(index, expression=expression):
        """Return store key for documents that satisfy expression."""
        ev = expression() if callable(expression) else expression
        if ev:
            return [
                store_key
                for store_keys
                in index.get_index().values()
                for store_key in store_keys
            ]
        else:
            return index.get_undefined_keys()

    return _exists


Instruction:
How would you implement a function in Python 3 that
returns a function that returns the store key for documents that satisfy the regular expression.

Response:
def regex_query(expression):
    """Apply regular expression to result of expression."""
    def _regex(index, expression=expression):
        """Return store key for documents that satisfy expression."""
        pattern = re.compile(expression)
        return [
            store_key
            for value, store_keys
            in index.get_index().items()
            if (isinstance(value, six.string_types)
                and re.match(pattern, value))
            for store_key in store_keys
        ]

    return _regex


Instruction:
Can you implement a function in Python 3 that
matches arrays that contain all elements in the query.

Response:
def all_query(expression):
    """Match arrays that contain all elements in the query."""
    def _all(index, expression=expression):
        """Return store key for documents that satisfy expression."""
        ev = expression() if callable(expression) else expression
        try:
            iter(ev)
        except TypeError:
            raise AttributeError('$all argument must be an iterable!')

        hashed_ev = [index.get_hash_for(v) for v in ev]
        store_keys = set()

        if len(hashed_ev) == 0:
            return []
        store_keys = set(index.get_keys_for(hashed_ev[0]))
        for value in hashed_ev[1:]:
            store_keys &= set(index.get_keys_for(value))
        return list(store_keys)

    return _all


Instruction:
Can you create a Python 3 function that
returns a function that returns the store key for documents that satisfy the given expression.

Response:
def in_query(expression):
    """Match any of the values that exist in an array specified in query."""
    def _in(index, expression=expression):
        """Return store key for documents that satisfy expression."""
        ev = expression() if callable(expression) else expression
        try:
            iter(ev)
        except TypeError:
            raise AttributeError('$in argument must be an iterable!')
        hashed_ev = [index.get_hash_for(v) for v in ev]
        store_keys = set()

        for value in hashed_ev:
            store_keys |= set(index.get_keys_for(value))

        return list(store_keys)

    return _in


Instruction:
How would you implement a function in Python 3 that
compiles each expression in query recursively.

Response:
def compile_query(query):
    """Compile each expression in query recursively."""
    if isinstance(query, dict):
        expressions = []
        for key, value in query.items():
            if key.startswith('$'):
                if key not in query_funcs:
                    raise AttributeError('Invalid operator: {}'.format(key))
                expressions.append(query_funcs[key](value))
            else:
                expressions.append(filter_query(key, value))
        if len(expressions) > 1:
            return boolean_operator_query(operator.and_)(expressions)
        else:
            return (
                expressions[0]
                if len(expressions)
                else lambda query_function: query_function(None, None)
            )
    else:
        return query


Instruction:
Can you tell what is the following Python 3 function doing
def environment_variable(key, value):

    if key not in os.environ:
        previous = None
    else:
        previous = os.environ[key]

    os.environ[key] = value

    yield

    if previous is None:
        del os.environ[key]
    else:
        os.environ[key] = previous

Response: Temporarily overrides an environment variable.


Instruction:
Create a Python 3 function to
hook this module up to the given api.

Response:
def hookup(self, api):
        """ Hooks this module up to the given api. """

        assert not hasattr(api, self.module_name), """
            '{}' conflicts with existing attribute
        """.format(self.module_name)

        self.api = api

        setattr(api, self.module_name, self.execute)


Instruction:
Can you write a function in Python 3 where it
executes the module and returns the result.

Response:
def execute(self, *args, **kwargs):
        """ Puts args and kwargs in a way ansible can understand. Calls ansible
        and interprets the result.

        """
        assert self.is_hooked_up, "the module should be hooked up to the api"

        if set_global_context:
            set_global_context(self.api.options)

        # legacy key=value pairs shorthand approach
        if args:
            self.module_args = module_args = self.get_module_args(args, kwargs)
        else:
            self.module_args = module_args = kwargs

        loader = DataLoader()
        inventory_manager = SourcelessInventoryManager(loader=loader)

        for host, port in self.api.hosts_with_ports:
            inventory_manager._inventory.add_host(host, group='all', port=port)

        for key, value in self.api.options.extra_vars.items():
            inventory_manager._inventory.set_variable('all', key, value)

        variable_manager = VariableManager(
            loader=loader, inventory=inventory_manager)

        play_source = {
            'name': "Suitable Play",
            'hosts': 'all',
            'gather_facts': 'no',
            'tasks': [{
                'action': {
                    'module': self.module_name,
                    'args': module_args,
                },
                'environment': self.api.environment,
            }]
        }

        try:
            play = Play.load(
                play_source,
                variable_manager=variable_manager,
                loader=loader,
            )

            if self.api.strategy:
                play.strategy = self.api.strategy

            log.info(
                u'running {}'.format(u'- {module_name}: {module_args}'.format(
                    module_name=self.module_name,
                    module_args=module_args
                ))
            )

            start = datetime.utcnow()
            task_queue_manager = None
            callback = SilentCallbackModule()

            # ansible uses various levels of verbosity (from -v to -vvvvvv)
            # offering various amounts of debug information
            #
            # we keep it a bit simpler by activating all of it during debug,
            # and falling back to the default of 0 otherwise
            verbosity = self.api.options.verbosity == logging.DEBUG and 6 or 0

            with ansible_verbosity(verbosity):

                # host_key_checking is special, since not each connection
                # plugin handles it the same way, we need to apply both
                # environment variable and Ansible constant when running a
                # command in the runner to be successful
                with host_key_checking(self.api.host_key_checking):
                    kwargs = dict(
                        inventory=inventory_manager,
                        variable_manager=variable_manager,
                        loader=loader,
                        options=self.api.options,
                        passwords=getattr(self.api.options, 'passwords', {}),
                        stdout_callback=callback
                    )

                    if set_global_context:
                        del kwargs['options']

                    task_queue_manager = TaskQueueManager(**kwargs)

                    try:
                        task_queue_manager.run(play)
                    except SystemExit:

                        # Mitogen forks our process and exits it in one
                        # instance before returning
                        #
                        # This is fine, but it does lead to a very messy exit
                        # by py.test which will essentially return with a test
                        # that is first successful and then failed as each
                        # forked process dies.
                        #
                        # To avoid this we commit suicide if we are run inside
                        # a pytest session. Normally this would just result
                        # in a exit code of zero, which is good.
                        if 'pytest' in sys.modules:
                            try:
                                atexit._run_exitfuncs()
                            except Exception:
                                pass
                            os.kill(os.getpid(), signal.SIGKILL)

                        raise
        finally:
            if task_queue_manager is not None:
                task_queue_manager.cleanup()

            if set_global_context:

                # Ansible 2.8 introduces a global context which persists
                # during the lifetime of the process - for Suitable this
                # singleton/cache needs to be cleared after each call
                # to make sure that API calls do not carry over state.
                #
                # The docs hint at a future inclusion of local contexts, which
                # would of course be preferable.
                from ansible.utils.context_objects import GlobalCLIArgs
                GlobalCLIArgs._Singleton__instance = None

        log.debug(u'took {} to complete'.format(datetime.utcnow() - start))

        return self.evaluate_results(callback)


Instruction:
Can you write a function in Python 3 where it
removes a server from the list of servers.

Response:
def ignore_further_calls_to_server(self, server):
        """ Takes a server out of the list. """
        log.error(u'ignoring further calls to {}'.format(server))
        self.api.servers.remove(server)


Instruction:
Can you create a Python 3 function that
evaluates the results of a runner call.

Response:
def evaluate_results(self, callback):
        """ prepare the result of runner call for use with RunnerResults. """

        for server, result in callback.unreachable.items():
            log.error(u'{} could not be reached'.format(server))
            log.debug(u'ansible-output =>\n{}'.format(pformat(result)))

            if self.api.ignore_unreachable:
                continue

            self.trigger_event(server, 'on_unreachable_host', (
                self, server
            ))

        for server, answer in callback.contacted.items():

            success = answer['success']
            result = answer['result']

            # none of the modules in our tests hit the 'failed' result
            # codepath (which seems to not be implemented by all modules)
            # seo we ignore this branch since it's rather trivial
            if result.get('failed'):  # pragma: no cover
                success = False

            if 'rc' in result:
                if self.api.is_valid_return_code(result['rc']):
                    success = True

            if not success:
                log.error(u'{} failed on {}'.format(self, server))
                log.debug(u'ansible-output =>\n{}'.format(pformat(result)))

                if self.api.ignore_errors:
                    continue

                self.trigger_event(server, 'on_module_error', (
                    self, server, result
                ))

        # XXX this is a weird structure because RunnerResults still works
        # like it did with Ansible 1.x, where the results where structured
        # like this
        return RunnerResults({
            'contacted': {
                server: answer['result']
                for server, answer in callback.contacted.items()
            }
        })


Instruction:
Given the following Python 3 function, write the documentation
def install_strategy_plugins(directories):
    if isinstance(directories, str):
        directories = directories.split(':')

    for directory in directories:
        strategy_loader.add_directory(directory)

Response: Installs the given strategy plugins.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def valid_return_codes(self, *codes):
        previous_codes = self._valid_return_codes
        self._valid_return_codes = codes

        yield

        self._valid_return_codes = previous_codes

Response: Sets codes which are considered valid when returned from a context module.


Instruction:
Create a Python 3 function for
constructing the URL with a given IP address.

Response:
def construct_url(ip_address: str) -> str:
    """Construct the URL with a given IP address."""
    if 'http://' not in ip_address and 'https://' not in ip_address:
        ip_address = '{}{}'.format('http://', ip_address)
    if ip_address[-1] == '/':
        ip_address = ip_address[:-1]
    return ip_address


Instruction:
Write a Python 3 script for
updating the data from the printer.

Response:
async def update(self) -> None:
        """
        Retrieve the data from the printer.
        Throws ValueError if host does not support SyncThru
        """
        url = '{}{}'.format(self.url, ENDPOINT)

        try:
            async with self._session.get(url) as response:
                json_dict = demjson.decode(await response.text(), strict=False)
        except aiohttp.ClientError:
            json_dict = {'status': {'status1': SyncThru.OFFLINE}}
        except demjson.JSONDecodeError:
            raise ValueError("Invalid host, does not support SyncThru.")
        self.data = json_dict


Instruction:
Can you implement a function in Python 3 that
returns the model name of the printer.

Response:
def model(self):
        """Return the model name of the printer."""
        try:
            return self.data.get('identity').get('model_name')
        except (KeyError, AttributeError):
            return self.device_status_simple('')


Instruction:
Make a summary of the following Python 3 code
def location(self):
        try:
            return self.data.get('identity').get('location')
        except (KeyError, AttributeError):
            return self.device_status_simple('')

Response: Return the location of the printer.


Instruction:
Can you generate the documentation for the following Python 3 function
def serial_number(self):
        try:
            return self.data.get('identity').get('serial_num')
        except (KeyError, AttributeError):
            return self.device_status_simple('')

Response: Return the serial number of the printer.


Instruction:
Implement a function in Python 3 to
return the hostname of the printer.

Response:
def hostname(self):
        """Return the hostname of the printer."""
        try:
            return self.data.get('identity').get('host_name')
        except (KeyError, AttributeError):
            return self.device_status_simple('')


Instruction:
Make a summary of the following Python 3 code
def device_status(self):
        try:
            return self.device_status_simple(
                self.data.get('status').get('status1'))
        except (KeyError, AttributeError):
            return self.device_status_simple('')

Response: Return the status of the device as string.


Instruction:
How would you explain what the following Python 3 function does
def capability(self) -> Dict[str, Any]:
        try:
            return self.data.get('capability', {})
        except (KeyError, AttributeError):
            return {}

Response: Return the capabilities of the printer.


Instruction:
How would you implement a function in Python 3 that
returns the state of all toners cartridges.

Response:
def toner_status(self, filter_supported: bool = True) -> Dict[str, Any]:
        """Return the state of all toners cartridges."""
        toner_status = {}
        for color in self.COLOR_NAMES:
            try:
                toner_stat = self.data.get(
                    '{}_{}'.format(SyncThru.TONER, color), {})
                if filter_supported and toner_stat.get('opt', 0) == 0:
                    continue
                else:
                    toner_status[color] = toner_stat
            except (KeyError, AttributeError):
                toner_status[color] = {}
        return toner_status


Instruction:
Implement a function in Python 3 to
return the state of all input trays.

Response:
def input_tray_status(self,
                          filter_supported: bool = True) -> Dict[int, Any]:
        """Return the state of all input trays."""
        tray_status = {}
        for i in range(1, 5):
            try:
                tray_stat = self.data.get('{}{}'.format(SyncThru.TRAY, i), {})
                if filter_supported and tray_stat.get('opt', 0) == 0:
                    continue
                else:
                    tray_status[i] = tray_stat
            except (KeyError, AttributeError):
                tray_status[i] = {}
        return tray_status


Instruction:
How would you code a function in Python 3 to
return the state of all output trays.

Response:
def output_tray_status(self) -> Dict[int, Dict[str, str]]:
        """Return the state of all output trays."""
        tray_status = {}
        try:
            tray_stat = self.data.get('outputTray', [])
            for i, stat in enumerate(tray_stat):
                tray_status[i] = {
                    'name': stat[0],
                    'capacity': stat[1],
                    'status': stat[2],
                }
        except (KeyError, AttributeError):
            tray_status = {}
        return tray_status


Instruction:
Write a Python 3 script for
returning the state of all drums.

Response:
def drum_status(self, filter_supported: bool = True) -> Dict[str, Any]:
        """Return the state of all drums."""
        drum_status = {}
        for color in self.COLOR_NAMES:
            try:
                drum_stat = self.data.get('{}_{}'.format(SyncThru.DRUM, color),
                                          {})
                if filter_supported and drum_stat.get('opt', 0) == 0:
                    continue
                else:
                    drum_status[color] = drum_stat
            except (KeyError, AttributeError):
                drum_status[color] = {}
        return drum_status


Instruction:
Write a Python 3 script to
call func with args and kwargs and runs pdb.

Response:
def pdb_run(func: Callable, *args: Any, **kwargs: Any) -> None:
    """
    Calls ``func(*args, **kwargs)``; if it raises an exception, break into
    the ``pdb`` debugger.
    """
    # noinspection PyBroadException
    try:
        func(*args, **kwargs)
    except:  # nopep8
        type_, value, tb = sys.exc_info()
        traceback.print_exc()
        pdb.post_mortem(tb)


Instruction:
How would you explain what the following Python 3 function does
def get_class_name_from_frame(fr: FrameType) -> Optional[str]:
    # http://stackoverflow.com/questions/2203424/python-how-to-retrieve-class-information-from-a-frame-object  # noqa
    args, _, _, value_dict = inspect.getargvalues(fr)
    # we check the first parameter for the frame function is named 'self'
    if len(args) and args[0] == 'self':
        # in that case, 'self' will be referenced in value_dict
        instance = value_dict.get('self', None)
        if instance:
            # return its class
            cls = getattr(instance, '__class__', None)
            if cls:
                return cls.__name__
            return None
    # return None otherwise
    return None

Response: This function attempts to retrieve the class name from a frame object.


Instruction:
Write a Python 3 script to
return details about the caller of this function.

Response:
def get_caller_name(back: int = 0) -> str:
    """
    Return details about the CALLER OF THE CALLER (plus n calls further back)
    of this function.

    So, if your function calls :func:`get_caller_name`, it will return the
    name of the function that called your function! (Or ``back`` calls further
    back.)

    Example:

    .. code-block:: python

        from cardinal_pythonlib.debugging import get_caller_name

        def who_am_i():
            return get_caller_name()

        class MyClass(object):
            def classfunc(self):
                print("I am: " + who_am_i())
                print("I was called by: " + get_caller_name())
                print("That was called by: " + get_caller_name(back=1))

        def f2():
            x = MyClass()
            x.classfunc()

        def f1():
            f2()

        f1()

    will produce:

    .. code-block:: none

        I am: MyClass.classfunc
        I was called by: f2
        That was called by: f1

    """
    # http://stackoverflow.com/questions/5067604/determine-function-name-from-within-that-function-without-using-traceback  # noqa
    try:
        # noinspection PyProtectedMember
        frame = sys._getframe(back + 2)
    except ValueError:
        # Stack isn't deep enough.
        return '?'
    function_name = frame.f_code.co_name
    class_name = get_class_name_from_frame(frame)
    if class_name:
        return "{}.{}".format(class_name, function_name)
    return function_name


Instruction:
Implement a function in Python 3 to
send details about a Python object to the log.

Response:
def debug_object(obj, log_level: int = logging.DEBUG) -> None:
    """
    Sends details about a Python to the log, specifically its ``repr()``
    representation, and all of its attributes with their name, value, and type.

    Args:
        obj: object to debug
        log_level: log level to use; default is ``logging.DEBUG``
    """
    msgs = ["For {o!r}:".format(o=obj)]
    for attrname in dir(obj):
        attribute = getattr(obj, attrname)
        msgs.append("- {an!r}: {at!r}, of type {t!r}".format(
            an=attrname, at=attribute, t=type(attribute)))
    log.log(log_level, "{}", "\n".join(msgs))


Instruction:
Can you generate the documentation for the following Python 3 function
def from_db_value(self, value, expression, connection, context):
        if value is None:
            return value
        return json_decode(value)

Response:
Called in all circumstances when the data is loaded from the
        database including in aggregates and values() calls.


Instruction:
Can you generate the documentation for the following Python 3 function
def parse(xml_input, encoding=None, expat=expat, process_namespaces=False,
          namespace_separator=':', **kwargs):
    """Parse the given XML input and convert it into a dictionary.

    `xml_input` can either be a `string` or a file-like object.

    If `xml_attribs` is `True`, element attributes are put in the dictionary
    among regular child elements, using `@` as a prefix to avoid collisions. If
    set to `False`, they are just ignored.

    Simple example::

        >>> import xmltodict
        >>> doc = xmltodict.parse(\"\"\"
        ...
        ...   1
        ...   2
        ...
        ... \"\"\")
        >>> doc['a']['@prop']
        u'x'
        >>> doc['a']['b']
        [u'1', u'2']

    If `item_depth` is `0`, the function returns a dictionary for the root
    element (default behavior). Otherwise, it calls `item_callback` every time
    an item at the specified depth is found and returns `None` in the end
    (streaming mode).

    The callback function receives two parameters: the `path` from the document
    root to the item (name-attribs pairs), and the `item` (dict). If the
    callback's return value is false-ish, parsing will be stopped with the
    :class:`ParsingInterrupted` exception.

    Streaming example::

        >>> def handle(path, item):
        ...     print 'path:%s item:%s' % (path, item)
        ...     return True
        ...
        >>> xmltodict.parse(\"\"\"
        ...
        ...   1
        ...   2
        ... \"\"\", item_depth=2, item_callback=handle)
        path:[(u'a', {u'prop': u'x'}), (u'b', None)] item:1
        path:[(u'a', {u'prop': u'x'}), (u'b', None)] item:2

    The optional argument `postprocessor` is a function that takes `path`,
    `key` and `value` as positional arguments and returns a new `(key, value)`
    pair where both `key` and `value` may have changed. Usage example::

        >>> def postprocessor(path, key, value):
        ...     try:
        ...         return key + ':int', int(value)
        ...     except (ValueError, TypeError):
        ...         return key, value
        >>> xmltodict.parse('12x',
        ...                 postprocessor=postprocessor)
        OrderedDict([(u'a', OrderedDict([(u'b:int', [1, 2]), (u'b', u'x')]))])

    You can pass an alternate version of `expat` (such as `defusedexpat`) by
    using the `expat` parameter. E.g:

        >>> import defusedexpat
        >>> xmltodict.parse('hello', expat=defusedexpat.pyexpat)
        OrderedDict([(u'a', u'hello')])

    You can use the force_list argument to force lists to be created even
    when there is only a single child of a given level of hierarchy. The
    force_list argument is a tuple of keys. If the key for a given level
    of hierarchy is in the force_list argument, that level of hierarchy
    will have a list as a child (even if there is only one sub-element).
    The index_keys operation takes precendence over this. This is applied
    after any user-supplied postprocessor has already run.

        For example, given this input:
        <servers>
          <server>
            <name>host1</name>
            <os>Linux</os>
            <interfaces>
              <interface>
                <name>em0</name>
                <ip_address>10.0.0.1</ip_address>
              </interface>
            </interfaces>
          </server>
        </servers>

        If called with force_list=('interface',), it will produce
        this dictionary:
        {'servers':
          {'server':
            {'name': 'host1',
             'os': 'Linux'},
             'interfaces':
              {'interface':
                [ {'name': 'em0', 'ip_address': '10.0.0.1' } ] } } }

        `force_list` can also be a callable that receives `path`, `key` and
        `value`. This is helpful in cases where the logic that decides whether
        a list should be forced is more complex.
    """
    handler = _DictSAXHandler(namespace_separator=namespace_separator,
                              **kwargs)
    if isinstance(xml_input, _unicode):
        if not encoding:
            encoding = 'utf-8'
        xml_input = xml_input.encode(encoding)
    if not process_namespaces:
        namespace_separator = None
    parser = expat.ParserCreate(
        encoding,
        namespace_separator
    )
    try:
        parser.ordered_attributes = True
    except AttributeError:
        # Jython's expat does not support ordered_attributes
        pass
    parser.StartElementHandler = handler.startElement
    parser.EndElementHandler = handler.endElement
    parser.CharacterDataHandler = handler.characters
    parser.buffer_text = True
    try:
        parser.ParseFile(xml_input)
    except (TypeError, AttributeError):
        parser.Parse(xml_input, True)
    return handler.item

Response: Parse the given XML input and return a dictionary.


Instruction:
Implement a Python 3 function for
matching C ++ class declarations.

Response:
def cxxRecordDecl(*args):
    """Matches C++ class declarations.

    >>> from glud import *
    >>> config = '''
    ...  class W;
    ...  template<typename T> class X {};
    ...  struct Y {};
    ...  union Z {};
    ... '''
    >>> m = cxxRecordDecl()
    >>> for c in walk(m, parse_string(config).cursor):
    ...     print(c.spelling)
    W
    X
    """
    kinds = [
        CursorKind.CLASS_DECL,
        CursorKind.CLASS_TEMPLATE,
    ]
    inner = [ PredMatcher(is_kind(k)) for k in kinds ]
    return allOf(anyOf(*inner), *args)


Instruction:
Create a Python 3 function to
match class struct and union declarations.

Response:
def recordDecl(*args):
    """Matches class, struct, and union declarations.

    >>> from glud import *
    >>> config = '''
    ...  class W;
    ...  template<typename T> class X {};
    ...  struct Y {};
    ...  union Z {};
    ... '''
    >>> m = recordDecl()
    >>> for c in walk(m, parse_string(config).cursor):
    ...     print(c.spelling)
    W
    X
    Y
    Z
    """
    kinds = [
        CursorKind.STRUCT_DECL,
        CursorKind.UNION_DECL,
        CursorKind.CLASS_DECL,
        CursorKind.CLASS_TEMPLATE,
    ]
    inner = [ PredMatcher(is_kind(k)) for k in kinds ]
    return allOf(anyOf(*inner), *args)


Instruction:
Explain what the following Python 3 code does
def convert_to_bool(x: Any, default: bool = None) -> bool:
    if isinstance(x, bool):
        return x

    if not x:  # None, zero, blank string...
        return default

    try:
        return int(x) != 0
    except (TypeError, ValueError):
        pass

    try:
        return float(x) != 0
    except (TypeError, ValueError):
        pass

    if not isinstance(x, str):
        raise Exception("Unknown thing being converted to bool: {!r}".format(x))

    x = x.upper()
    if x in ["Y", "YES", "T", "TRUE"]:
        return True
    if x in ["N", "NO", "F", "FALSE"]:
        return False

    raise Exception("Unknown thing being converted to bool: {!r}".format(x))

Response: Converts a string or integer to a boolean.


Instruction:
How would you explain what the following Python 3 function does
def convert_to_int(x: Any, default: int = None) -> int:
    try:
        return int(x)
    except (TypeError, ValueError):
        return default

Response: Transforms its input into an integer or returns default.


Instruction:
Given the following Python 3 function, write the documentation
def convert_attrs_to_bool(obj: Any,
                          attrs: Iterable[str],
                          default: bool = None) -> None:
    """
    Applies :func:`convert_to_bool` to the specified attributes of an object,
    modifying it in place.
    """
    for a in attrs:
        setattr(obj, a, convert_to_bool(getattr(obj, a), default=default))

Response: Applies convert_to_bool to the specified attributes of an object.


Instruction:
Can you generate the documentation for the following Python 3 function
def convert_attrs_to_uppercase(obj: Any, attrs: Iterable[str]) -> None:
    for a in attrs:
        value = getattr(obj, a)
        if value is None:
            continue
        setattr(obj, a, value.upper())

Response: Converts the specified attributes of an object to upper case.


Instruction:
Can you generate the documentation for the following Python 3 function
def convert_attrs_to_lowercase(obj: Any, attrs: Iterable[str]) -> None:
    for a in attrs:
        value = getattr(obj, a)
        if value is None:
            continue
        setattr(obj, a, value.lower())

Response: Converts the specified attributes of an object to lower case.


Instruction:
Explain what the following Python 3 code does
def convert_attrs_to_int(obj: Any,
                         attrs: Iterable[str],
                         default: int = None) -> None:
    """
    Applies :func:`convert_to_int` to the specified attributes of an object,
    modifying it in place.
    """
    for a in attrs:
        value = convert_to_int(getattr(obj, a), default=default)
        setattr(obj, a, value)

Response: Applies convert_to_int to the specified attributes of an object.


Instruction:
Write a Python 3 script to
decode a string into a byte array.

Response:
def hex_xformat_decode(s: str) -> Optional[bytes]:
    """
    Reverse :func:`hex_xformat_encode`.

    The parameter is a hex-encoded BLOB like

    .. code-block:: none

        "X'CDE7A24B1A9DBA3148BCB7A0B9DA5BB6A424486C'"

    Original purpose and notes:

    - SPECIAL HANDLING for BLOBs: a string like ``X'01FF'`` means a hex-encoded
      BLOB. Titanium is rubbish at BLOBs, so we encode them as special string
      literals.
    - SQLite uses this notation: https://sqlite.org/lang_expr.html
    - Strip off the start and end and convert it to a byte array:
      http://stackoverflow.com/questions/5649407
    """
    if len(s) < 3 or not s.startswith("X'") or not s.endswith("'"):
        return None
    return binascii.unhexlify(s[2:-1])


Instruction:
Create a Python 3 function to
decode base64 encoded string.

Response:
def base64_64format_decode(s: str) -> Optional[bytes]:
    """
    Reverse :func:`base64_64format_encode`.

    Original purpose and notes:

    - THIS IS ANOTHER WAY OF DOING BLOBS: base64 encoding, e.g. a string like
      ``64'cGxlYXN1cmUu'`` is a base-64-encoded BLOB (the ``64'...'`` bit is my
      representation).
    - regex from http://stackoverflow.com/questions/475074
    - better one from http://www.perlmonks.org/?node_id=775820

    """
    if len(s) < 4 or not s.startswith("64'") or not s.endswith("'"):
        return None
    return base64.b64decode(s[3:-1])


Instruction:
Can you write a function in Python 3 where it
fetches a setting from the environment.

Response:
def environ_setting(name, default=None, required=True):
    """
    Fetch setting from the environment. The bahavior of the setting if it
    is not in environment is as follows:

        1. If it is required and the default is None, raise Exception
        2. If it is requried and a default exists, return default
        3. If it is not required and default is None, return  None
        4. If it is not required and default exists, return default
    """
    if name not in os.environ and default is None:
        message = "The {0} ENVVAR is not set.".format(name)
        if required:
            raise ImproperlyConfigured(message)
        else:
            warnings.warn(ConfigurationMissing(message))

    return os.environ.get(name, default)


Instruction:
Can you generate the documentation for the following Python 3 function
def load(klass):
        config = klass()
        for path in klass.CONF_PATHS:
            if os.path.exists(path):
                with open(path, 'r') as conf:
                    config.configure(yaml.safe_load(conf))
        return config

Response:
Loads the configuration from YAML files specified by the CONF_PATH module
        variable.


Instruction:
Write a Python 3 function that can
allow updating of the configuration of the object via a dictionary of configuration terms or a configuration object. Generally speaking this method is utilized to configure the object from a JSON or a YAML parsing.

Response:
def configure(self, conf={}):
        """
        Allows updating of the configuration via a dictionary of
        configuration terms or a configuration object. Generally speaking,
        this method is utilized to configure the object from a JSON or
        YAML parsing.
        """
        if not conf: return
        if isinstance(conf, Configuration):
            conf = dict(conf.options())
        for key, value in conf.items():
            opt = self.get(key, None)
            if isinstance(opt, Configuration):
                opt.configure(value)
            else:
                setattr(self, key, value)


Instruction:
How would you explain what the following Python 3 function does
def options(self):
        keys = self.__class__.__dict__.copy()
        keys.update(self.__dict__)
        keys = sorted(keys.keys())

        for opt in keys:
            val = self.get(opt)
            if val is not None:
                yield opt, val

Response: Returns an iterable of sorted option names and values for all the configuration directives in the class.


Instruction:
Create a Python 3 function for
formatting a datetime. date to ISO - 8601 basic format.

Response:
def formatdt(date: datetime.date, include_time: bool = True) -> str:
    """
    Formats a ``datetime.date`` to ISO-8601 basic format, to minute accuracy
    with no timezone (or, if ``include_time`` is ``False``, omit the time).
    """
    if include_time:
        return date.strftime("%Y-%m-%dT%H:%M")
    else:
        return date.strftime("%Y-%m-%d")


Instruction:
Create a Python 3 function for
converting a datetime. timedelta object into other units.

Response:
def convert_duration(duration: datetime.timedelta,
                     units: str) -> Optional[float]:
    """
    Convert a ``datetime.timedelta`` object -- a duration -- into other
    units. Possible units:

        ``s``, ``sec``, ``seconds``
        ``m``, ``min``, ``minutes``
        ``h``, ``hr``, ``hours``
        ``d``, ``days``
        ``w``, ``weeks``
        ``y``, ``years``
    """
    if duration is None:
        return None
    s = duration.total_seconds()
    if units in ['s', 'sec', 'seconds']:
        return s
    if units in ['m', 'min', 'minutes']:
        return s / SECONDS_PER_MINUTE
    if units in ['h', 'hr', 'hours']:
        return s / SECONDS_PER_HOUR
    if units in ['d', 'days']:
        return s / SECONDS_PER_DAY
    if units in ['w', 'weeks']:
        return s / SECONDS_PER_WEEK
    if units in ['y', 'years']:
        return s / SECONDS_PER_YEAR
    raise ValueError("Unknown units: {}".format(units))


Instruction:
Make a summary of the following Python 3 code
def overlaps(self, other: "Interval") -> bool:
        return not(self.end <= other.start or self.start >= other.end)

Response: Returns True if this interval overlaps other.


Instruction:
Explain what the following Python 3 code does
def contiguous(self, other: "Interval") -> bool:
        return not(self.end < other.start or self.start > other.end)

Response: Is this interval contiguous?


Instruction:
Can you write a function in Python 3 where it
returns True if the interval contains the given time.

Response:
def contains(self, time: datetime.datetime,
                 inclusive: bool = True) -> bool:
        """
        Does the interval contain a momentary time?

        Args:
            time: the ``datetime.datetime`` to check
            inclusive: use inclusive rather than exclusive range checks?
        """
        if inclusive:
            return self.start <= time <= self.end
        else:
            return self.start < time < self.end


Instruction:
Create a Python 3 function for
returning True if this interval is contained within the other.

Response:
def within(self, other: "Interval", inclusive: bool = True) -> bool:
        """
        Is this interval contained within the other?

        Args:
            other: the :class:`Interval` to check
            inclusive: use inclusive rather than exclusive range checks?
        """
        if not other:
            return False
        if inclusive:
            return self.start >= other.start and self.end <= other.end
        else:
            return self.start > other.start and self.end < other.end


Instruction:
Can you generate the documentation for the following Python 3 function
def intersection(self, other: "Interval") -> Optional["Interval"]:
        if not self.contiguous(other):
            return None
        return Interval(
            max(self.start, other.start),
            min(self.end, other.end)
        )

Response: Returns an interval representing the intersection of this and the other.


Instruction:
Can you write a function in Python 3 where it
returns a list of intervals produced by using times as a list of knives to slice this interval.

Response:
def cut(self, times: Union[datetime.datetime,
                               List[datetime.datetime]]) -> List["Interval"]:
        """
        Returns a list of intervals produced by using times (a list of
        ``datetime.datetime`` objects, or a single such object) as a set of
        knives to slice this interval.
        """
        if not isinstance(times, list):
            # Single time
            time = times
            if not self.contains(time):
                return []
            return [
                Interval(self.start, time),
                Interval(time, self.end)
            ]
        else:
            # Multiple times
            times = [t for t in times if self.contains(t)]  # discard others
            times.sort()
            times = [self.start] + times + [self.end]
            intervals = []
            for i in range(len(times) - 1):
                intervals.append(Interval(times[i], times[i + 1]))
            return intervals


Instruction:
Can you implement a function in Python 3 that
returns an interval covering the given date.

Response:
def wholeday(date: datetime.date) -> "Interval":
        """
        Returns an :class:`Interval` covering the date given (midnight at the
        start of that day to midnight at the start of the next day).
        """
        start = datetime.datetime.combine(date, datetime.time())
        return Interval(
            start,
            start + datetime.timedelta(days=1)
        )


Instruction:
Can you create a Python 3 function that
returns an :class:`Interval` representing daytime on the date given.

Response:
def daytime(date: datetime.date,
                daybreak: datetime.time = datetime.time(NORMAL_DAY_START_H),
                nightfall: datetime.time = datetime.time(NORMAL_DAY_END_H)) \
            -> "Interval":
        """
        Returns an :class:`Interval` representing daytime on the date given.
        """
        return Interval(
            datetime.datetime.combine(date, daybreak),
            datetime.datetime.combine(date, nightfall),
        )


Instruction:
Implement a function in Python 3 to
return an interval representing the date range given from startdate to enddate.

Response:
def dayspan(startdate: datetime.date,
                enddate: datetime.date,
                include_end: bool = True) -> Optional["Interval"]:
        """
        Returns an :class:`Interval` representing the date range given, from
        midnight at the start of the first day to midnight at the end of the
        last (i.e. at the start of the next day after the last), or if
        include_end is False, 24h before that.

        If the parameters are invalid, returns ``None``.
        """
        if enddate < startdate:
            return None
        if enddate == startdate and include_end:
            return None
        start_dt = datetime.datetime.combine(startdate, datetime.time())
        end_dt = datetime.datetime.combine(enddate, datetime.time())
        if include_end:
            end_dt += datetime.timedelta(days=1)
        return Interval(start_dt, end_dt)


Instruction:
How would you implement a function in Python 3 that
returns the part of this interval that falls on the given date.

Response:
def component_on_date(self, date: datetime.date) -> Optional["Interval"]:
        """
        Returns the part of this interval that falls on the date given, or
        ``None`` if the interval doesn't have any part during that date.
        """
        return self.intersection(Interval.wholeday(date))


Instruction:
Create a Python 3 function for
returning a tuple of the duration of this interval that falls into day and night.

Response:
def day_night_duration(
            self,
            daybreak: datetime.time = datetime.time(NORMAL_DAY_START_H),
            nightfall: datetime.time = datetime.time(NORMAL_DAY_END_H)) \
            -> Tuple[datetime.timedelta, datetime.timedelta]:
        """
        Returns a ``(day, night)`` tuple of ``datetime.timedelta`` objects
        giving the duration of this interval that falls into day and night
        respectively.
        """
        daytotal = datetime.timedelta()
        nighttotal = datetime.timedelta()
        startdate = self.start.date()
        enddate = self.end.date()
        ndays = (enddate - startdate).days + 1
        for i in range(ndays):
            date = startdate + datetime.timedelta(days=i)
            component = self.component_on_date(date)
            # ... an interval on a single day
            day = Interval.daytime(date, daybreak, nightfall)
            daypart = component.intersection(day)
            if daypart is not None:
                daytotal += daypart.duration()
                nighttotal += component.duration() - daypart.duration()
            else:
                nighttotal += component.duration()
        return daytotal, nighttotal


Instruction:
Implement a Python 3 function for
returning the number of hours outside the given time range.

Response:
def duration_outside_nwh(
            self,
            starttime: datetime.time = datetime.time(NORMAL_DAY_START_H),
            endtime: datetime.time = datetime.time(NORMAL_DAY_END_H),
            weekdays_only: bool = False,
            weekends_only: bool = False) -> datetime.timedelta:
        """
        Returns a duration (a ``datetime.timedelta`` object) representing the
        number of hours outside normal working hours.

        This is not simply a subset of :meth:`day_night_duration`, because
        weekends are treated differently (they are always out of hours).

        The options allow the calculation of components on weekdays or weekends
        only.
        """
        if weekdays_only and weekends_only:
            raise ValueError("Can't have weekdays_only and weekends_only")
        ooh = datetime.timedelta()  # ooh = out of (normal) hours
        startdate = self.start.date()
        enddate = self.end.date()
        ndays = (enddate - startdate).days + 1
        for i in range(ndays):
            date = startdate + datetime.timedelta(days=i)
            component = self.component_on_date(date)
            # ... an interval on a single day
            if not is_normal_working_day(date):
                if weekdays_only:
                    continue
                ooh += component.duration()  # all is out-of-normal-hours
            else:
                if weekends_only:
                    continue
                normalday = Interval.daytime(date, starttime, endtime)
                normalpart = component.intersection(normalday)
                if normalpart is not None:
                    ooh += component.duration() - normalpart.duration()
                else:
                    ooh += component.duration()
        return ooh


Instruction:
Here you have a function in Python 3, explain what it does
def saturdays_of_weekends(self) -> Set[datetime.date]:
        startdate = self.start.date()
        enddate = self.end.date()
        ndays = (enddate - startdate).days + 1
        saturdays = set()
        for i in range(ndays):
            date = startdate + datetime.timedelta(days=i)
            if is_saturday(date):
                saturdays.add(date)
            elif is_sunday(date):
                saturdays.add(date - datetime.timedelta(days=1))
        return saturdays

Response: Returns the set of dates of all Saturdays that this calendar contains.


Instruction:
Can you generate the documentation for the following Python 3 function
def copy(self, no_overlap: bool = None,
             no_contiguous: bool = None) -> "IntervalList":
        """
        Makes and returns a copy of the :class:`IntervalList`. The
        ``no_overlap``/``no_contiguous`` parameters can be changed.

        Args:
            no_overlap: merge intervals that overlap (now and on subsequent
                addition)?
            no_contiguous: if ``no_overlap`` is set, merge intervals that are
                contiguous too?
        """
        if no_overlap is None:
            no_overlap = self.no_overlap
        if no_contiguous is None:
            no_contiguous = self.no_contiguous
        return IntervalList(self.intervals, no_overlap=no_overlap,
                            no_contiguous=no_contiguous)

Response: Makes and returns a copy of the : class : IntervalList.


Instruction:
Create a Python 3 function for
adding an interval to the list.

Response:
def add(self, interval: Interval) -> None:
        """
        Adds an interval to the list. If ``self.no_overlap`` is True, as is the
        default, it will merge any overlapping intervals thus created.
        """
        if interval is None:
            return
        if not isinstance(interval, Interval):
            raise TypeError(
                "Attempt to insert non-Interval into IntervalList")
        self.intervals.append(interval)
        self._tidy()


Instruction:
Can you write a function in Python 3 where it
removes overlaps etc. and sorts.

Response:
def _tidy(self) -> None:
        """
        Removes overlaps, etc., and sorts.
        """
        if self.no_overlap:
            self.remove_overlap(self.no_contiguous)  # will sort
        else:
            self._sort()


Instruction:
Make a summary of the following Python 3 code
def _remove_overlap_sub(self, also_remove_contiguous: bool) -> bool:
        # Returns
        for i in range(len(self.intervals)):
            for j in range(i + 1, len(self.intervals)):
                first = self.intervals[i]
                second = self.intervals[j]
                if also_remove_contiguous:
                    test = first.contiguous(second)
                else:
                    test = first.overlaps(second)
                if test:
                    newint = first.union(second)
                    self.intervals.pop(j)
                    self.intervals.pop(i)  # note that i must be less than j
                    self.intervals.append(newint)
                    return True
        return False

Response: Called by _remove_overlap to remove the first overlap found.


Instruction:
How would you code a function in Python 3 to
remove any overlapping intervals.

Response:
def remove_overlap(self, also_remove_contiguous: bool = False) -> None:
        """
        Merges any overlapping intervals.

        Args:
            also_remove_contiguous: treat contiguous (as well as overlapping)
                intervals as worthy of merging?
        """
        overlap = True
        while overlap:
            overlap = self._remove_overlap_sub(also_remove_contiguous)
        self._sort()


Instruction:
Can you generate the documentation for the following Python 3 function
def _any_overlap_or_contiguous(self, test_overlap: bool) -> bool:
        for i in range(len(self.intervals)):
            for j in range(i + 1, len(self.intervals)):
                first = self.intervals[i]
                second = self.intervals[j]
                if test_overlap:
                    test = first.overlaps(second)
                else:
                    test = first.contiguous(second)
                if test:
                    return True
        return False

Response: Test if any of the intervals overlap?


Instruction:
Explain what the following Python 3 code does
def start_datetime(self) -> Optional[datetime.datetime]:
        if not self.intervals:
            return None
        return self.intervals[0].start

Response: Returns the start date of the set of intervals or None if there is no start date.


Instruction:
Given the following Python 3 function, write the documentation
def end_datetime(self) -> Optional[datetime.datetime]:
        if not self.intervals:
            return None
        return max([x.end for x in self.intervals])

Response: Returns the end date of the set of intervals or None if there is no end date.


Instruction:
Create a Python 3 function for
returning the start date of the set of intervals or None if there is no start date.

Response:
def start_date(self) -> Optional[datetime.date]:
        """
        Returns the start date of the set of intervals, or ``None`` if empty.
        """
        if not self.intervals:
            return None
        return self.start_datetime().date()


Instruction:
Make a summary of the following Python 3 code
def end_date(self) -> Optional[datetime.date]:
        if not self.intervals:
            return None
        return self.end_datetime().date()

Response: Returns the end date of the set of intervals or None if there is no end date.


Instruction:
Implement a function in Python 3 to
return the earliest start of an interval running to the latest end of the anatomical set.

Response:
def extent(self) -> Optional[Interval]:
        """
        Returns an :class:`Interval` running from the earliest start of an
        interval in this list to the latest end. Returns ``None`` if we are
        empty.
        """
        if not self.intervals:
            return None
        return Interval(self.start_datetime(), self.end_datetime())


Instruction:
Implement a Python 3 function for
returning the total sum of all the time - counted durations of all the items in the set.

Response:
def total_duration(self) -> datetime.timedelta:
        """
        Returns a ``datetime.timedelta`` object with the total sum of
        durations. If there is overlap, time will be double-counted, so beware!
        """
        total = datetime.timedelta()
        for interval in self.intervals:
            total += interval.duration()
        return total


Instruction:
Make a summary of the following Python 3 code
def get_overlaps(self) -> "IntervalList":
        overlaps = IntervalList()
        for i in range(len(self.intervals)):
            for j in range(i + 1, len(self.intervals)):
                first = self.intervals[i]
                second = self.intervals[j]
                ol = first.intersection(second)
                if ol is not None:
                    overlaps.add(ol)
        return overlaps

Response: Returns an intervalList containing intervals representing periods of overlap between intervals in this one.


Instruction:
Can you tell what is the following Python 3 function doing
def durations(self) -> List[datetime.timedelta]:
        return [x.duration() for x in self.intervals]

Response: Returns a list of datetime. timedelta objects representing the durations of each interval in our list.


Instruction:
Create a Python 3 function for
returning the duration of the longest interval.

Response:
def longest_duration(self) -> Optional[datetime.timedelta]:
        """
        Returns the duration of the longest interval, or None if none.
        """
        if not self.intervals:
            return None
        return max(self.durations())


Instruction:
Can you write a function in Python 3 where it
returns the longest interval in the archive or None if none.

Response:
def longest_interval(self) -> Optional[Interval]:
        """
        Returns the longest interval, or ``None`` if none.
        """
        longest_duration = self.longest_duration()
        for i in self.intervals:
            if i.duration() == longest_duration:
                return i
        return None


Instruction:
Write a Python 3 script for
returning the first interval that starts with the start parameter or None if no interval is found.

Response:
def first_interval_starting(self, start: datetime.datetime) -> \
            Optional[Interval]:
        """
        Returns our first interval that starts with the ``start`` parameter, or
        ``None``.
        """
        for i in self.intervals:
            if i.start == start:
                return i
        return None


Instruction:
Write a Python 3 function that can
return the first interval that ends with the end parameter or None if no interval is found.

Response:
def first_interval_ending(self, end: datetime.datetime) \
            -> Optional[Interval]:
        """
        Returns our first interval that ends with the ``end`` parameter, or
        ``None``.
        """
        for i in self.intervals:
            if i.end == end:
                return i
        return None


Instruction:
Implement a Python 3 function for
returning all the gaps between intervals as an : class:`IntervalList.

Response:
def gaps(self) -> "IntervalList":
        """
        Returns all the gaps between intervals, as an :class:`IntervalList`.
        """
        if len(self.intervals) < 2:
            return IntervalList(None)
        gaps = []
        for i in range(len(self.intervals) - 1):
            gap = Interval(
                self.intervals[i].end,
                self.intervals[i + 1].start
            )
            gaps.append(gap)
        return IntervalList(gaps)


Instruction:
Can you generate the documentation for the following Python 3 function
def subset(self, interval: Interval,
               flexibility: int = 2) -> "IntervalList":
        """
        Returns an IntervalList that's a subset of this one, only containing
        intervals that meet the "interval" parameter criterion. What "meet"
        means is defined by the ``flexibility`` parameter.

        ``flexibility == 0``: permits only wholly contained intervals:

        .. code-block:: none

            interval:
                        I----------------I

            intervals in self that will/won't be returned:

                N---N  N---N   Y---Y   N---N   N---N
                    N---N                N---N

        ``flexibility == 1``: permits overlapping intervals as well:

        .. code-block:: none

                        I----------------I

                N---N  Y---Y   Y---Y   Y---Y   N---N
                    N---N                N---N

        ``flexibility == 2``: permits adjoining intervals as well:

        .. code-block:: none

                        I----------------I

                N---N  Y---Y   Y---Y   Y---Y   N---N
                    Y---Y                Y---Y
        """
        if flexibility not in [0, 1, 2]:
            raise ValueError("subset: bad flexibility value")
        permitted = []
        for i in self.intervals:
            if flexibility == 0:
                ok = i.start > interval.start and i.end < interval.end
            elif flexibility == 1:
                ok = i.end > interval.start and i.start < interval.end
            else:
                ok = i.end >= interval.start and i.start <= interval.end
            if ok:
                permitted.append(i)
        return IntervalList(permitted)

Response: Returns an IntervalList that s a subset of this one with only containing intervals that meet the interval criterion.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def gap_subset(self, interval: Interval,
                   flexibility: int = 2) -> "IntervalList":
        """
        Returns an IntervalList that's a subset of this one, only containing
        *gaps* between intervals that meet the interval criterion.

        See :meth:`subset` for the meaning of parameters.
        """
        return self.gaps().subset(interval, flexibility)

Response: Returns an IntervalList that s a subset of this one only containing gaps between intervals that meet the interval criterion.


Instruction:
Create a Python 3 function for
returning the number of weekends that the intervals collectively touch .

Response:
def n_weekends(self) -> int:
        """
        Returns the number of weekends that the intervals collectively touch
        (where "touching a weekend" means "including time on a Saturday or a
        Sunday").
        """
        saturdays = set()
        for interval in self.intervals:
            saturdays.update(interval.saturdays_of_weekends())
        return len(saturdays)


Instruction:
Can you tell what is the following Python 3 function doing
def duration_outside_nwh(
            self,
            starttime: datetime.time = datetime.time(NORMAL_DAY_START_H),
            endtime: datetime.time = datetime.time(NORMAL_DAY_END_H)) \
            -> datetime.timedelta:
        """
        Returns the total duration outside normal working hours, i.e.
        evenings/nights, weekends (and Bank Holidays).
        """
        total = datetime.timedelta()
        for interval in self.intervals:
            total += interval.duration_outside_nwh(starttime, endtime)
        return total

Response: Returns the total duration of the sequence of time intervals that are outside the normal working hours.


Instruction:
Make a summary of the following Python 3 code
def max_consecutive_days(self) -> Optional[Tuple[int, Interval]]:
        if len(self.intervals) == 0:
            return None
        startdate = self.start_date()
        enddate = self.end_date()
        seq = ''
        ndays = (enddate - startdate).days + 1
        for i in range(ndays):
            date = startdate + datetime.timedelta(days=i)
            wholeday = Interval.wholeday(date)
            if any([x.overlaps(wholeday) for x in self.intervals]):
                seq += '+'
            else:
                seq += ' '
        # noinspection PyTypeChecker
        longest = max(seq.split(), key=len)
        longest_len = len(longest)
        longest_idx = seq.index(longest)
        longest_interval = Interval.dayspan(
            startdate + datetime.timedelta(days=longest_idx),
            startdate + datetime.timedelta(days=longest_idx + longest_len)
        )
        return longest_len, longest_interval

Response: Returns the length of the longest sequence of days in which all days include the longest interval.


Instruction:
Explain what the following Python 3 code does
def _sufficient_gaps(self,
                         startdate: datetime.date,
                         enddate: datetime.date,
                         requiredgaps: List[datetime.timedelta],
                         flexibility: int) -> Tuple[bool, Optional[Interval]]:
        """
        Are there sufficient gaps (specified by ``requiredgaps``) in the date
        range specified? This is a worker function for :meth:`sufficient_gaps`.
        """
        requiredgaps = list(requiredgaps)  # make a copy
        interval = Interval.dayspan(startdate, enddate, include_end=True)
        # log.debug(">>> _sufficient_gaps")
        gaps = self.gap_subset(interval, flexibility)
        gapdurations = gaps.durations()
        gaplist = gaps.list()
        gapdurations.sort(reverse=True)  # longest gap first
        requiredgaps.sort(reverse=True)  # longest gap first
        # log.debug("... gaps = {}".format(gaps))
        # log.debug("... gapdurations = {}".format(gapdurations))
        # log.debug("... requiredgaps = {}".format(requiredgaps))
        while requiredgaps:
            # log.debug("... processing gap")
            if not gapdurations:
                # log.debug("<<< no gaps left")
                return False, None
            if gapdurations[0] < requiredgaps[0]:
                # log.debug("<<< longest gap is too short")
                return False, self.first_interval_ending(gaplist[0].start)
            gapdurations.pop(0)
            requiredgaps.pop(0)
            gaplist.pop(0)
            # ... keeps gaplist and gapdurations mapped to each other
        # log.debug("<<< success")
        return True, None

Response: This is a worker function for the _sufficient_gaps method. It returns True if there are sufficient gaps in the date range specified?


Instruction:
Given the following Python 3 function, write the documentation
def sufficient_gaps(self,
                        every_n_days: int,
                        requiredgaps: List[datetime.timedelta],
                        flexibility: int = 2) \
            -> Tuple[bool, Optional[Interval]]:
        """
        Are gaps present sufficiently often?
        For example:

        .. code-block:: python

            every_n_days=21
            requiredgaps=[
                datetime.timedelta(hours=62),
                datetime.timedelta(hours=48),
            ]

        ... means "is there at least one 62-hour gap and one (separate) 48-hour
        gap in every possible 21-day sequence within the IntervalList?

        - If ``flexibility == 0``: gaps must be WHOLLY WITHIN the interval.

        - If ``flexibility == 1``: gaps may OVERLAP the edges of the interval.

        - If ``flexibility == 2``: gaps may ABUT the edges of the interval.

        Returns ``(True, None)`` or ``(False, first_failure_interval)``.
        """
        if len(self.intervals) < 2:
            return False, None
        startdate = self.start_date()
        enddate = self.end_date()
        ndays = (enddate - startdate).days + 1
        if ndays <= every_n_days:
            # Our interval is too short, or just right
            return self._sufficient_gaps(startdate, enddate, requiredgaps,
                                         flexibility)
        for i in range(ndays - every_n_days):
            j = i + every_n_days
            a = startdate + datetime.timedelta(days=i)
            b = startdate + datetime.timedelta(days=j)
            sufficient, ffi = self._sufficient_gaps(a, b, requiredgaps,
                                                    flexibility)
            if not sufficient:
                return False, ffi
        return True, None

Response: Check if a set of gaps are present sufficiently often.


Instruction:
Here you have a function in Python 3, explain what it does
def cumulative_time_to(self,
                           when: datetime.datetime) -> datetime.timedelta:
        """
        Returns the cumulative time contained in our intervals up to the
        specified time point.
        """
        assert self.no_overlap, self._ONLY_FOR_NO_INTERVAL
        cumulative = datetime.timedelta()
        for interval in self.intervals:
            if interval.start >= when:
                break
            elif interval.end <= when:
                # complete interval precedes "when"
                cumulative += interval.duration()
            else:  # start < when < end
                cumulative += when - interval.start
        return cumulative

Response: Returns the cumulative time contained in our intervals up to the given time point.


Instruction:
Given the following Python 3 function, write the documentation
def cumulative_gaps_to(self,
                           when: datetime.datetime) -> datetime.timedelta:
        """
        Return the cumulative time within our gaps, up to ``when``.
        """
        gaps = self.gaps()
        return gaps.cumulative_time_to(when)

Response: Return the cumulative time within our gaps up to when.


Instruction:
Create a Python 3 function to
return the time after our last interval but before when.

Response:
def time_afterwards_preceding(
            self, when: datetime.datetime) -> Optional[datetime.timedelta]:
        """
        Returns the time after our last interval, but before ``when``.
        If ``self`` is an empty list, returns ``None``.
        """
        if self.is_empty():
            return None
        end_time = self.end_datetime()
        if when <= end_time:
            return datetime.timedelta()
        else:
            return when - end_time


Instruction:
Write a Python 3 script for
returning the cumulative time before and during the given time.

Response:
def cumulative_before_during_after(self,
                                       start: datetime.datetime,
                                       when: datetime.datetime) -> \
            Tuple[datetime.timedelta,
                  datetime.timedelta,
                  datetime.timedelta]:
        """
        For a given time, ``when``, returns the cumulative time

        - after ``start`` but before ``self`` begins, prior to ``when``;
        - after ``start`` and during intervals represented by ``self``, prior
          to ``when``;
        - after ``start`` and after at least one interval represented by
          ``self`` has finished, and not within any intervals represented by
          ``self``, and prior to ``when``.

        Args:
            start: the start time of interest (e.g. before ``self`` begins)
            when: the time of interest

        Returns:
            tuple: ``before, during, after``

        Illustration

        .. code-block:: none

            start:      S
            self:           X---X       X---X       X---X       X---X

            when:                                           W

            before:     ----
            during:         -----       -----       -----
            after:               -------     -------     ----

        """
        assert self.no_overlap, (
            "Only implemented for IntervalList objects with no_overlap == True"
        )
        no_time = datetime.timedelta()
        earliest_interval_start = self.start_datetime()

        # Easy special cases
        if when <= start:
            return no_time, no_time, no_time
        if self.is_empty() or when <= earliest_interval_start:
            return when - start, no_time, no_time

        # Now we can guarantee:
        # - "self" is a non-empty list
        # - start < when
        # - earliest_interval_start < when

        # Before
        if earliest_interval_start < start:
            before = no_time
        else:
            before = earliest_interval_start - start

        # During
        during = self.cumulative_time_to(when)

        after = (
            self.cumulative_gaps_to(when) +
            self.time_afterwards_preceding(when)
        )

        return before, during, after


Instruction:
Here you have a function in Python 3, explain what it does
def repr_parameter(param: inspect.Parameter) -> str:
    return (
        "Parameter(name={name}, annotation={annotation}, kind={kind}, "
        "default={default}".format(
            name=param.name, annotation=param.annotation, kind=param.kind,
            default=param.default)
    )

Response: Provides a repr - style representation of a function parameter.


Instruction:
Can you create a Python 3 function that
returns a representation of a function s name in a namespace.

Response:
def get_namespace(fn: Callable, namespace: Optional[str]) -> str:
    """
    Returns a representation of a function's name (perhaps within a namespace),
    like

    .. code-block:: none

        mymodule:MyClass.myclassfunc  # with no namespace
        mymodule:MyClass.myclassfunc|somenamespace  # with a namespace

    Args:
        fn: a function
        namespace: an optional namespace, which can be of any type but is
            normally a ``str``; if not ``None``, ``str(namespace)`` will be
            added to the result. See
            https://dogpilecache.readthedocs.io/en/latest/api.html#dogpile.cache.region.CacheRegion.cache_on_arguments
    """  # noqa
    # See hidden attributes with dir(fn)
    # noinspection PyUnresolvedReferences
    return "{module}:{name}{extra}".format(
        module=fn.__module__,
        name=fn.__qualname__,  # __qualname__ includes class name, if present
        extra="|{}".format(namespace) if namespace is not None else "",
    )