Instruction:
Explain what the following Python 3 code does
def generate_model_cls(config, schema, model_name, raml_resource,
                       es_based=True):
    """ Generate model class.

    Engine DB field types are determined using `type_fields` and only those
    types may be used.

    :param schema: Model schema dict parsed from RAML.
    :param model_name: String that is used as new model's name.
    :param raml_resource: Instance of ramlfications.raml.ResourceNode.
    :param es_based: Boolean indicating if generated model should be a
        subclass of Elasticsearch-based document class or not.
        It True, ESBaseDocument is used; BaseDocument is used otherwise.
        Defaults to True.
    """
    from nefertari.authentication.models import AuthModelMethodsMixin
    base_cls = engine.ESBaseDocument if es_based else engine.BaseDocument
    model_name = str(model_name)
    metaclass = type(base_cls)
    auth_model = schema.get('_auth_model', False)

    bases = []
    if config.registry.database_acls:
        from nefertari_guards import engine as guards_engine
        bases.append(guards_engine.DocumentACLMixin)
    if auth_model:
        bases.append(AuthModelMethodsMixin)
    bases.append(base_cls)

    attrs = {
        '__tablename__': model_name.lower(),
        '_public_fields': schema.get('_public_fields') or [],
        '_auth_fields': schema.get('_auth_fields') or [],
        '_hidden_fields': schema.get('_hidden_fields') or [],
        '_nested_relationships': schema.get('_nested_relationships') or [],
    }
    if '_nesting_depth' in schema:
        attrs['_nesting_depth'] = schema.get('_nesting_depth')

    # Generate fields from properties
    properties = schema.get('properties', {})
    for field_name, props in properties.items():
        if field_name in attrs:
            continue

        db_settings = props.get('_db_settings')
        if db_settings is None:
            continue

        field_kwargs = db_settings.copy()
        field_kwargs['required'] = bool(field_kwargs.get('required'))

        for default_attr_key in ('default', 'onupdate'):
            value = field_kwargs.get(default_attr_key)
            if is_callable_tag(value):
                field_kwargs[default_attr_key] = resolve_to_callable(value)

        type_name = (
            field_kwargs.pop('type', 'string') or 'string').lower()
        if type_name not in type_fields:
            raise ValueError('Unknown type: {}'.format(type_name))

        field_cls = type_fields[type_name]

        if field_cls is engine.Relationship:
            prepare_relationship(
                config, field_kwargs['document'],
                raml_resource)
        if field_cls is engine.ForeignKeyField:
            key = 'ref_column_type'
            field_kwargs[key] = type_fields[field_kwargs[key]]
        if field_cls is engine.ListField:
            key = 'item_type'
            field_kwargs[key] = type_fields[field_kwargs[key]]

        attrs[field_name] = field_cls(**field_kwargs)

    # Update model definition with methods and variables defined in registry
    attrs.update(registry.mget(model_name))

    # Generate new model class
    model_cls = metaclass(model_name, tuple(bases), attrs)
    setup_model_event_subscribers(config, model_cls, schema)
    setup_fields_processors(config, model_cls, schema)
    return model_cls, auth_model

Response: Generate a new model class.


Instruction:
Explain what the following Python 3 code does
def handle_model_generation(config, raml_resource):
    model_name = generate_model_name(raml_resource)
    try:
        return setup_data_model(config, raml_resource, model_name)
    except ValueError as ex:
        raise ValueError('{}: {}'.format(model_name, str(ex)))

Response:
Generates model name and runs setup_data_model to get
    or generate actual model class.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def setup_model_event_subscribers(config, model_cls, schema):
    events_map = get_events_map()
    model_events = schema.get('_event_handlers', {})
    event_kwargs = {'model': model_cls}

    for event_tag, subscribers in model_events.items():
        type_, action = event_tag.split('_')
        event_objects = events_map[type_][action]

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

        for sub_name in subscribers:
            sub_func = resolve_to_callable(sub_name)
            config.subscribe_to_events(
                sub_func, event_objects, **event_kwargs)

Response: Setup model event subscribers.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def setup_fields_processors(config, model_cls, schema):
    properties = schema.get('properties', {})
    for field_name, props in properties.items():
        if not props:
            continue

        processors = props.get('_processors')
        backref_processors = props.get('_backref_processors')

        if processors:
            processors = [resolve_to_callable(val) for val in processors]
            setup_kwargs = {'model': model_cls, 'field': field_name}
            config.add_field_processors(processors, **setup_kwargs)

        if backref_processors:
            db_settings = props.get('_db_settings', {})
            is_relationship = db_settings.get('type') == 'relationship'
            document = db_settings.get('document')
            backref_name = db_settings.get('backref_name')
            if not (is_relationship and document and backref_name):
                continue

            backref_processors = [
                resolve_to_callable(val) for val in backref_processors]
            setup_kwargs = {
                'model': engine.get_document_cls(document),
                'field': backref_name
            }
            config.add_field_processors(
                backref_processors, **setup_kwargs)

Response: Setup model fields processors.


Instruction:
Given the following Python 3 function, write the documentation
def get_authuser_model():
    from nefertari.authentication.models import AuthUserMixin
    from nefertari import engine

    class AuthUser(AuthUserMixin, engine.BaseDocument):
        __tablename__ = 'ramses_authuser'

    return AuthUser

Response: Define and return AuthUser model using nefertari base classes


Instruction:
Can you tell what is the following Python 3 function doing
def validate_permissions(perms):
    if not isinstance(perms, (list, tuple)):
        perms = [perms]
    valid_perms = set(PERMISSIONS.values())
    if ALL_PERMISSIONS in perms:
        return perms
    if set(perms) - valid_perms:
        raise ValueError(
            'Invalid ACL permission names. Valid permissions '
            'are: {}'.format(', '.join(valid_perms)))
    return perms

Response:
Validate :perms: contains valid permissions.

    :param perms: List of permission names or ALL_PERMISSIONS.


Instruction:
Can you tell what is the following Python 3 function doing
def parse_permissions(perms):
    if isinstance(perms, six.string_types):
        perms = perms.split(',')
    perms = [perm.strip().lower() for perm in perms]
    if 'all' in perms:
        return ALL_PERMISSIONS
    return validate_permissions(perms)

Response:
Parse permission names which are either exact permission
    names or the keyword all.


Instruction:
Explain what the following Python 3 code does
def parse_acl(acl_string):
    if not acl_string:
        return [ALLOW_ALL]

    aces_list = acl_string.replace('\n', ';').split(';')
    aces_list = [ace.strip().split(' ', 2) for ace in aces_list if ace]
    aces_list = [(a, b, c.split(',')) for a, b, c in aces_list]
    result_acl = []

    for action_str, princ_str, perms in aces_list:
        # Process action
        action_str = action_str.strip().lower()
        action = actions.get(action_str)
        if action is None:
            raise ValueError(
                'Unknown ACL action: {}. Valid actions: {}'.format(
                    action_str, list(actions.keys())))

        # Process principal
        princ_str = princ_str.strip().lower()
        if princ_str in special_principals:
            principal = special_principals[princ_str]
        elif is_callable_tag(princ_str):
            principal = resolve_to_callable(princ_str)
        else:
            principal = princ_str

        # Process permissions
        permissions = parse_permissions(perms)

        result_acl.append((action, principal, permissions))

    return result_acl

Response: Parses a string containing a list of ACEs and returns a list of ACEs.


Instruction:
Here you have a function in Python 3, explain what it does
def generate_acl(config, model_cls, raml_resource, es_based=True):
    schemes = raml_resource.security_schemes or []
    schemes = [sch for sch in schemes if sch.type == 'x-ACL']

    if not schemes:
        collection_acl = item_acl = []
        log.debug('No ACL scheme applied. Using ACL: {}'.format(item_acl))
    else:
        sec_scheme = schemes[0]
        log.debug('{} ACL scheme applied'.format(sec_scheme.name))
        settings = sec_scheme.settings or {}
        collection_acl = parse_acl(acl_string=settings.get('collection'))
        item_acl = parse_acl(acl_string=settings.get('item'))

    class GeneratedACLBase(object):
        item_model = model_cls

        def __init__(self, request, es_based=es_based):
            super(GeneratedACLBase, self).__init__(request=request)
            self.es_based = es_based
            self._collection_acl = collection_acl
            self._item_acl = item_acl

    bases = [GeneratedACLBase]
    if config.registry.database_acls:
        from nefertari_guards.acl import DatabaseACLMixin as GuardsMixin
        bases += [DatabaseACLMixin, GuardsMixin]
    bases.append(BaseACL)

    return type('GeneratedACL', tuple(bases), {})

Response:
Generate an ACL.

    Generated ACL class has a `item_model` attribute set to
    :model_cls:.

    ACLs used for collection and item access control are generated from a
    first security scheme with type `x-ACL`.
    If :raml_resource: has no x-ACL security schemes defined then ALLOW_ALL
    ACL is used.
    If the `collection` or `item` settings are empty, then ALLOW_ALL ACL
    is used.

    :param model_cls: Generated model class
    :param raml_resource: Instance of ramlfications.raml.ResourceNode
        for which ACL is being generated
    :param es_based: Boolean inidicating whether ACL should query ES or
        not when getting an object


Instruction:
Can you write a function in Python 3 where it
iterates over ACEs from acl and apply callable principals to the object instance.

Response:
def _apply_callables(self, acl, obj=None):
        """ Iterate over ACEs from :acl: and apply callable principals
        if any.

        Principals are passed 3 arguments on call:
            :ace: Single ACE object that looks like (action, callable,
                permission or [permission])
            :request: Current request object
            :obj: Object instance to be accessed via the ACL
        Principals must return a single ACE or a list of ACEs.

        :param acl: Sequence of valid Pyramid ACEs which will be processed
        :param obj: Object to be accessed via the ACL
        """
        new_acl = []
        for i, ace in enumerate(acl):
            principal = ace[1]
            if six.callable(principal):
                ace = principal(ace=ace, request=self.request, obj=obj)
                if not ace:
                    continue
                if not isinstance(ace[0], (list, tuple)):
                    ace = [ace]
                ace = [(a, b, validate_permissions(c)) for a, b, c in ace]
            else:
                ace = [ace]
            new_acl += ace
        return tuple(new_acl)


Instruction:
Write a Python 3 script for
returning the objectify ACL for the given item.

Response:
def item_acl(self, item):
        """ Objectify ACL if ES is used or call item.get_acl() if
        db is used.
        """
        if self.es_based:
            from nefertari_guards.elasticsearch import get_es_item_acl
            return get_es_item_acl(item)
        return super(DatabaseACLMixin, self).item_acl(item)


Instruction:
Here you have a function in Python 3, explain what it does
def getitem_es(self, key):
        from nefertari_guards.elasticsearch import ACLFilterES
        es = ACLFilterES(self.item_model.__name__)
        params = {
            'id': key,
            'request': self.request,
        }
        obj = es.get_item(**params)
        obj.__acl__ = self.item_acl(obj)
        obj.__parent__ = self
        obj.__name__ = key
        return obj

Response: Override to support ACL filtering.


Instruction:
Write a Python 3 script for
converting a RAML schema to a dictionary that has properties and other schema keys and values.

Response:
def convert_schema(raml_schema, mime_type):
    """ Restructure `raml_schema` to a dictionary that has 'properties'
    as well as other schema keys/values.

    The resulting dictionary looks like this::

    {
        "properties": {
            "field1": {
                "required": boolean,
                "type": ...,
                ...more field options
            },
            ...more properties
        },
        "public_fields": [...],
        "auth_fields": [...],
        ...more schema options
    }

    :param raml_schema: RAML request body schema.
    :param mime_type: ContentType of the schema as a string from RAML
        file. Only JSON is currently supported.
    """
    if mime_type == ContentTypes.JSON:
        if not isinstance(raml_schema, dict):
            raise TypeError(
                'Schema is not a valid JSON. Please check your '
                'schema syntax.\n{}...'.format(str(raml_schema)[:60]))
        return raml_schema
    if mime_type == ContentTypes.TEXT_XML:
        # Process XML schema
        pass


Instruction:
Create a Python 3 function for
generating model name. :param raml_resource: Instance of ramlfications.raml.ResourceNode.

Response:
def generate_model_name(raml_resource):
    """ Generate model name.

    :param raml_resource: Instance of ramlfications.raml.ResourceNode.
    """
    resource_uri = get_resource_uri(raml_resource).strip('/')
    resource_uri = re.sub('\W', ' ', resource_uri)
    model_name = inflection.titleize(resource_uri)
    return inflection.singularize(model_name).replace(' ', '')


Instruction:
How would you explain what the following Python 3 function does
def dynamic_part_name(raml_resource, route_name, pk_field):
    subresources = get_resource_children(raml_resource)
    dynamic_uris = [res.path for res in subresources
                    if is_dynamic_uri(res.path)]
    if dynamic_uris:
        dynamic_part = extract_dynamic_part(dynamic_uris[0])
    else:
        dynamic_part = pk_field
    return '_'.join([route_name, dynamic_part])

Response: Generate a dynamic part name for a resource.


Instruction:
Make a summary of the following Python 3 code
def extract_dynamic_part(uri):
    for part in uri.split('/'):
        part = part.strip()
        if part.startswith('{') and part.endswith('}'):
            return clean_dynamic_uri(part)

Response: Extract dynamic url part from URI string.


Instruction:
How would you explain what the following Python 3 function does
def resource_view_attrs(raml_resource, singular=False):
    from .views import collection_methods, item_methods
    # Singular resource doesn't have collection methods though
    # it looks like a collection
    if singular:
        collection_methods = item_methods

    siblings = get_resource_siblings(raml_resource)
    http_methods = [sibl.method.lower() for sibl in siblings]
    attrs = [collection_methods.get(method) for method in http_methods]

    # Check if resource has dynamic child resource like collection/{id}
    # If dynamic child resource exists, add its siblings' methods to attrs,
    # as both resources are handled by a single view
    children = get_resource_children(raml_resource)
    http_submethods = [child.method.lower() for child in children
                       if is_dynamic_uri(child.path)]
    attrs += [item_methods.get(method) for method in http_submethods]

    return set(filter(bool, attrs))

Response: Generate view method names needed for a resource node.


Instruction:
Write a Python 3 function for
getting schema properties of a resource.

Response:
def resource_schema(raml_resource):
    """ Get schema properties of RAML resource :raml_resource:.

    Must be called with RAML resource that defines body schema. First
    body that defines schema is used. Schema is converted on return using
    'convert_schema'.

    :param raml_resource: Instance of ramlfications.raml.ResourceNode of
        POST method.
    """
    # NOTE: Must be called with resource that defines body schema
    log.info('Searching for model schema')
    if not raml_resource.body:
        raise ValueError('RAML resource has no body to setup database '
                         'schema from')

    for body in raml_resource.body:
        if body.schema:
            return convert_schema(body.schema, body.mime_type)
    log.debug('No model schema found.')


Instruction:
Make a summary of the following Python 3 code
def get_static_parent(raml_resource, method=None):
    parent = raml_resource.parent
    while is_dynamic_resource(parent):
        parent = parent.parent

    if parent is None:
        return parent

    match_method = method is not None
    if match_method:
        if parent.method.upper() == method.upper():
            return parent
    else:
        return parent

    for res in parent.root.resources:
        if res.path == parent.path:
            if res.method.upper() == method.upper():
                return res

Response: Get static parent resource of the resource with HTTP method method.


Instruction:
Write a Python 3 function for
determining if the given resource is an attribute subresource.

Response:
def attr_subresource(raml_resource, route_name):
    """ Determine if :raml_resource: is an attribute subresource.

    :param raml_resource: Instance of ramlfications.raml.ResourceNode.
    :param route_name: Name of the :raml_resource:.
    """
    static_parent = get_static_parent(raml_resource, method='POST')
    if static_parent is None:
        return False
    schema = resource_schema(static_parent) or {}
    properties = schema.get('properties', {})
    if route_name in properties:
        db_settings = properties[route_name].get('_db_settings', {})
        return db_settings.get('type') in ('dict', 'list')
    return False


Instruction:
Implement a function in Python 3 to
determine if the resource is a singular subresource.

Response:
def singular_subresource(raml_resource, route_name):
    """ Determine if :raml_resource: is a singular subresource.

    :param raml_resource: Instance of ramlfications.raml.ResourceNode.
    :param route_name: Name of the :raml_resource:.
    """
    static_parent = get_static_parent(raml_resource, method='POST')
    if static_parent is None:
        return False
    schema = resource_schema(static_parent) or {}
    properties = schema.get('properties', {})
    if route_name not in properties:
        return False

    db_settings = properties[route_name].get('_db_settings', {})
    is_obj = db_settings.get('type') == 'relationship'
    single_obj = not db_settings.get('uselist', True)
    return is_obj and single_obj


Instruction:
Write a Python 3 function that can
determine whether a tag is a valid callable string.

Response:
def is_callable_tag(tag):
    """ Determine whether :tag: is a valid callable string tag.

    String is assumed to be valid callable if it starts with '{{'
    and ends with '}}'.

    :param tag: String name of tag.
    """
    return (isinstance(tag, six.string_types) and
            tag.strip().startswith('{{') and
            tag.strip().endswith('}}'))


Instruction:
Write a Python 3 function for
resolving string to a callable.

Response:
def resolve_to_callable(callable_name):
    """ Resolve string :callable_name: to a callable.

    :param callable_name: String representing callable name as registered
        in ramses registry or dotted import path of callable. Can be
        wrapped in double curly brackets, e.g. '{{my_callable}}'.
    """
    from . import registry
    clean_callable_name = callable_name.replace(
        '{{', '').replace('}}', '').strip()
    try:
        return registry.get(clean_callable_name)
    except KeyError:
        try:
            from zope.dottedname.resolve import resolve
            return resolve(clean_callable_name)
        except ImportError:
            raise ImportError(
                'Failed to load callable `{}`'.format(clean_callable_name))


Instruction:
Create a Python 3 function for
getting siblings of a resource node.

Response:
def get_resource_siblings(raml_resource):
    """ Get siblings of :raml_resource:.

    :param raml_resource: Instance of ramlfications.raml.ResourceNode.
    """
    path = raml_resource.path
    return [res for res in raml_resource.root.resources
            if res.path == path]


Instruction:
Here you have a function in Python 3, explain what it does
def get_resource_children(raml_resource):
    path = raml_resource.path
    return [res for res in raml_resource.root.resources
            if res.parent and res.parent.path == path]

Response: Get children of a resource.


Instruction:
Write a Python 3 function that can
prepare a map of event subscribers.

Response:
def get_events_map():
    """ Prepare map of event subscribers.

    * Extends copies of BEFORE_EVENTS and AFTER_EVENTS maps with
        'set' action.
    * Returns map of {before/after: {action: event class(es)}}
    """
    from nefertari import events
    set_keys = ('create', 'update', 'replace', 'update_many', 'register')
    before_events = events.BEFORE_EVENTS.copy()
    before_events['set'] = [before_events[key] for key in set_keys]
    after_events = events.AFTER_EVENTS.copy()
    after_events['set'] = [after_events[key] for key in set_keys]
    return {
        'before': before_events,
        'after': after_events,
    }


Instruction:
How would you code a function in Python 3 to
patch view_cls. Model with model_cls.

Response:
def patch_view_model(view_cls, model_cls):
    """ Patches view_cls.Model with model_cls.

    :param view_cls: View class "Model" param of which should be
        patched
    :param model_cls: Model class which should be used to patch
        view_cls.Model
    """
    original_model = view_cls.Model
    view_cls.Model = model_cls

    try:
        yield
    finally:
        view_cls.Model = original_model


Instruction:
Create a Python 3 function to
get route name from RAML resource URI.

Response:
def get_route_name(resource_uri):
    """ Get route name from RAML resource URI.

    :param resource_uri: String representing RAML resource URI.
    :returns string: String with route name, which is :resource_uri:
        stripped of non-word characters.
    """
    resource_uri = resource_uri.strip('/')
    resource_uri = re.sub('\W', '', resource_uri)
    return resource_uri


Instruction:
Can you implement a function in Python 3 that
generates nefertari resource structure for a given resource.

Response:
def generate_resource(config, raml_resource, parent_resource):
    """ Perform complete one resource configuration process

    This function generates: ACL, view, route, resource, database
    model for a given `raml_resource`. New nefertari resource is
    attached to `parent_resource` class which is an instance of
    `nefertari.resource.Resource`.

    Things to consider:
      * Top-level resources must be collection names.
      * No resources are explicitly created for dynamic (ending with '}')
        RAML resources as they are implicitly processed by parent collection
        resources.
      * Resource nesting must look like collection/id/collection/id/...
      * Only part of resource path after last '/' is taken into account,
        thus each level of resource nesting should add one more path
        element. E.g. /stories -> /stories/{id} and not
        /stories -> /stories/mystories/{id}. Latter route will be generated
        at /stories/{id}.

    :param raml_resource: Instance of ramlfications.raml.ResourceNode.
    :param parent_resource: Parent nefertari resource object.
    """
    from .models import get_existing_model

    # Don't generate resources for dynamic routes as they are already
    # generated by their parent
    resource_uri = get_resource_uri(raml_resource)
    if is_dynamic_uri(resource_uri):
        if parent_resource.is_root:
            raise Exception("Top-level resources can't be dynamic and must "
                            "represent collections instead")
        return

    route_name = get_route_name(resource_uri)
    log.info('Configuring resource: `{}`. Parent: `{}`'.format(
        route_name, parent_resource.uid or 'root'))

    # Get DB model. If this is an attribute or singular resource,
    # we don't need to get model
    is_singular = singular_subresource(raml_resource, route_name)
    is_attr_res = attr_subresource(raml_resource, route_name)
    if not parent_resource.is_root and (is_attr_res or is_singular):
        model_cls = parent_resource.view.Model
    else:
        model_name = generate_model_name(raml_resource)
        model_cls = get_existing_model(model_name)

    resource_kwargs = {}

    # Generate ACL
    log.info('Generating ACL for `{}`'.format(route_name))
    resource_kwargs['factory'] = generate_acl(
        config,
        model_cls=model_cls,
        raml_resource=raml_resource)

    # Generate dynamic part name
    if not is_singular:
        resource_kwargs['id_name'] = dynamic_part_name(
            raml_resource=raml_resource,
            route_name=route_name,
            pk_field=model_cls.pk_field())

    # Generate REST view
    log.info('Generating view for `{}`'.format(route_name))
    view_attrs = resource_view_attrs(raml_resource, is_singular)
    resource_kwargs['view'] = generate_rest_view(
        config,
        model_cls=model_cls,
        attrs=view_attrs,
        attr_view=is_attr_res,
        singular=is_singular,
    )

    # In case of singular resource, model still needs to be generated,
    # but we store it on a different view attribute
    if is_singular:
        model_name = generate_model_name(raml_resource)
        view_cls = resource_kwargs['view']
        view_cls._parent_model = view_cls.Model
        view_cls.Model = get_existing_model(model_name)

    # Create new nefertari resource
    log.info('Creating new resource for `{}`'.format(route_name))
    clean_uri = resource_uri.strip('/')
    resource_args = (singularize(clean_uri),)
    if not is_singular:
        resource_args += (clean_uri,)

    return parent_resource.add(*resource_args, **resource_kwargs)


Instruction:
Make a summary of the following Python 3 code
def generate_server(raml_root, config):
    log.info('Server generation started')

    if not raml_root.resources:
        return

    root_resource = config.get_root_resource()
    generated_resources = {}

    for raml_resource in raml_root.resources:
        if raml_resource.path in generated_resources:
            continue

        # Get Nefertari parent resource
        parent_resource = _get_nefertari_parent_resource(
            raml_resource, generated_resources, root_resource)

        # Get generated resource and store it
        new_resource = generate_resource(
            config, raml_resource, parent_resource)
        if new_resource is not None:
            generated_resources[raml_resource.path] = new_resource

Response: Generate server resources for a given RAML file.


Instruction:
Given the following Python 3 function, write the documentation
def generate_models(config, raml_resources):
    from .models import handle_model_generation
    if not raml_resources:
        return
    for raml_resource in raml_resources:
        # No need to generate models for dynamic resource
        if is_dynamic_uri(raml_resource.path):
            continue

        # Since POST resource must define schema use only POST
        # resources to generate models
        if raml_resource.method.upper() != 'POST':
            continue

        # Generate DB model
        # If this is an attribute resource we don't need to generate model
        resource_uri = get_resource_uri(raml_resource)
        route_name = get_route_name(resource_uri)
        if not attr_subresource(raml_resource, route_name):
            log.info('Configuring model for route `{}`'.format(route_name))
            model_cls, is_auth_model = handle_model_generation(
                config, raml_resource)
            if is_auth_model:
                config.registry.auth_model = model_cls

Response: Generate models for each resource in the list of resource nodes.


Instruction:
How would you explain what the following Python 3 function does
def generate_rest_view(config, model_cls, attrs=None, es_based=True,
                       attr_view=False, singular=False):
    """ Generate REST view for a model class.

    :param model_cls: Generated DB model class.
    :param attr: List of strings that represent names of view methods, new
        generated view should support. Not supported methods are replaced
        with property that raises AttributeError to display MethodNotAllowed
        error.
    :param es_based: Boolean indicating if generated view should read from
        elasticsearch. If True - collection reads are performed from
        elasticsearch. Database is used for reads otherwise.
        Defaults to True.
    :param attr_view: Boolean indicating if ItemAttributeView should be
        used as a base class for generated view.
    :param singular: Boolean indicating if ItemSingularView should be
        used as a base class for generated view.
    """
    valid_attrs = (list(collection_methods.values()) +
                   list(item_methods.values()))
    missing_attrs = set(valid_attrs) - set(attrs)

    if singular:
        bases = [ItemSingularView]
    elif attr_view:
        bases = [ItemAttributeView]
    elif es_based:
        bases = [ESCollectionView]
    else:
        bases = [CollectionView]

    if config.registry.database_acls:
        from nefertari_guards.view import ACLFilterViewMixin
        bases = [SetObjectACLMixin] + bases + [ACLFilterViewMixin]
    bases.append(NefertariBaseView)

    RESTView = type('RESTView', tuple(bases), {'Model': model_cls})

    def _attr_error(*args, **kwargs):
        raise AttributeError

    for attr in missing_attrs:
        setattr(RESTView, attr, property(_attr_error))

    return RESTView

Response: Generate REST view for a given model class.


Instruction:
Can you tell what is the following Python 3 function doing
def set_object_acl(self, obj):
        if not obj._acl:
            from nefertari_guards import engine as guards_engine
            acl = self._factory(self.request).generate_item_acl(obj)
            obj._acl = guards_engine.ACLField.stringify_acl(acl)

Response: Set object ACL on creation if not already present.


Instruction:
Make a summary of the following Python 3 code
def resolve_kw(self, kwargs):
        resolved = {}
        for key, value in kwargs.items():
            split = key.split('_', 1)
            if len(split) > 1:
                key = split[1]
            resolved[key] = value
        return resolved

Response: Resolve keyword arguments to the form of id 1.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _location(self, obj):
        field_name = self.clean_id_name
        return self.request.route_url(
            self._resource.uid,
            **{self._resource.id_name: getattr(obj, field_name)})

Response: Returns the URL of the object in the resource.


Instruction:
Can you generate the documentation for the following Python 3 function
def _parent_queryset(self):
        parent = self._resource.parent
        if hasattr(parent, 'view'):
            req = self.request.blank(self.request.path)
            req.registry = self.request.registry
            req.matchdict = {
                parent.id_name: self.request.matchdict.get(parent.id_name)}
            parent_view = parent.view(parent.view._factory, req)
            obj = parent_view.get_item(**req.matchdict)
            if isinstance(self, ItemSubresourceBaseView):
                return
            prop = self._resource.collection_name
            return getattr(obj, prop, None)

Response: Get queryset of parent view.


Instruction:
Write a Python 3 script for
getting objects collection taking into account generated queryset of parent view.

Response:
def get_collection(self, **kwargs):
        """ Get objects collection taking into account generated queryset
        of parent view.

        This method allows working with nested resources properly. Thus a
        queryset returned by this method will be a subset of its parent
        view's queryset, thus filtering out objects that don't belong to
        the parent object.
        """
        self._query_params.update(kwargs)
        objects = self._parent_queryset()
        if objects is not None:
            return self.Model.filter_objects(
                objects, **self._query_params)
        return self.Model.get_collection(**self._query_params)


Instruction:
Write a Python 3 function for
getting the item from the parent view.

Response:
def get_item(self, **kwargs):
        """ Get collection item taking into account generated queryset
        of parent view.

        This method allows working with nested resources properly. Thus an item
        returned by this method will belong to its parent view's queryset, thus
        filtering out objects that don't belong to the parent object.

        Returns an object from the applicable ACL. If ACL wasn't applied, it is
        applied explicitly.
        """
        if six.callable(self.context):
            self.reload_context(es_based=False, **kwargs)

        objects = self._parent_queryset()
        if objects is not None and self.context not in objects:
            raise JHTTPNotFound('{}({}) not found'.format(
                self.Model.__name__,
                self._get_context_key(**kwargs)))

        return self.context


Instruction:
Can you create a Python 3 function that
reloads the current context object into a DB or ES object.

Response:
def reload_context(self, es_based, **kwargs):
        """ Reload `self.context` object into a DB or ES object.

        A reload is performed by getting the object ID from :kwargs: and then
        getting a context key item from the new instance of `self._factory`
        which is an ACL class used by the current view.

        Arguments:
            :es_based: Boolean. Whether to init ACL ac es-based or not. This
                affects the backend which will be queried - either DB or ES
            :kwargs: Kwargs that contain value for current resource 'id_name'
                key
        """
        from .acl import BaseACL
        key = self._get_context_key(**kwargs)
        kwargs = {'request': self.request}
        if issubclass(self._factory, BaseACL):
            kwargs['es_based'] = es_based

        acl = self._factory(**kwargs)
        if acl.item_model is None:
            acl.item_model = self.Model

        self.context = acl[key]


Instruction:
Can you write a function in Python 3 where it
gets queryset of objects of parent view.

Response:
def _parent_queryset_es(self):
        """ Get queryset (list of object IDs) of parent view.

        The generated queryset is used to run queries in the current level's
        view.
        """
        parent = self._resource.parent
        if hasattr(parent, 'view'):
            req = self.request.blank(self.request.path)
            req.registry = self.request.registry
            req.matchdict = {
                parent.id_name: self.request.matchdict.get(parent.id_name)}
            parent_view = parent.view(parent.view._factory, req)
            obj = parent_view.get_item_es(**req.matchdict)
            prop = self._resource.collection_name
            objects_ids = getattr(obj, prop, None)
            return objects_ids


Instruction:
Create a Python 3 function for
returning the set of IDs of the objects in the ES database.

Response:
def get_es_object_ids(self, objects):
        """ Return IDs of :objects: if they are not IDs already. """
        id_field = self.clean_id_name
        ids = [getattr(obj, id_field, obj) for obj in objects]
        return list(set(str(id_) for id_ in ids))


Instruction:
Can you create a Python 3 function that
gets ES objects collection taking into account the generated queryset of parent view.

Response:
def get_collection_es(self):
        """ Get ES objects collection taking into account the generated
        queryset of parent view.

        This method allows working with nested resources properly. Thus a
        queryset returned by this method will be a subset of its parent view's
        queryset, thus filtering out objects that don't belong to the parent
        object.
        """
        objects_ids = self._parent_queryset_es()

        if objects_ids is not None:
            objects_ids = self.get_es_object_ids(objects_ids)
            if not objects_ids:
                return []
            self._query_params['id'] = objects_ids

        return super(ESBaseView, self).get_collection_es()


Instruction:
Can you tell what is the following Python 3 function doing
def get_item_es(self, **kwargs):
        item_id = self._get_context_key(**kwargs)
        objects_ids = self._parent_queryset_es()
        if objects_ids is not None:
            objects_ids = self.get_es_object_ids(objects_ids)

        if six.callable(self.context):
            self.reload_context(es_based=True, **kwargs)

        if (objects_ids is not None) and (item_id not in objects_ids):
            raise JHTTPNotFound('{}(id={}) resource not found'.format(
                self.Model.__name__, item_id))

        return self.context

Response:
Get an ES collection item taking into account generated queryset
        of parent view.


Instruction:
Given the following Python 3 function, write the documentation
def get_dbcollection_with_es(self, **kwargs):
        es_objects = self.get_collection_es()
        db_objects = self.Model.filter_objects(es_objects)
        return db_objects

Response: Get DB objects collection by first querying ES.


Instruction:
Make a summary of the following Python 3 code
def delete_many(self, **kwargs):
        db_objects = self.get_dbcollection_with_es(**kwargs)
        return self.Model._delete_many(db_objects, self.request)

Response: Delete multiple objects from collection.


Instruction:
Can you generate the documentation for the following Python 3 function
def update_many(self, **kwargs):
        db_objects = self.get_dbcollection_with_es(**kwargs)
        return self.Model._update_many(
            db_objects, self._json_params, self.request)

Response: Update multiple objects from collection.


Instruction:
Can you tell what is the following Python 3 function doing
def _get_context_key(self, **kwargs):
        return str(kwargs.get(self._resource.parent.id_name))

Response: Get value of self. _resource. parent. id_name from kwargs.


Instruction:
Write a Python 3 script to
reload context on each access.

Response:
def get_item(self, **kwargs):
        """ Reload context on each access. """
        self.reload_context(es_based=False, **kwargs)
        return super(ItemSubresourceBaseView, self).get_item(**kwargs)


Instruction:
Given the following Python 3 function, write the documentation
def setup(app):
    import sphinxcontrib_django.docstrings
    import sphinxcontrib_django.roles

    # Setup both modules at once. They can also be separately imported to
    # use only fragments of this package.
    sphinxcontrib_django.docstrings.setup(app)
    sphinxcontrib_django.roles.setup(app)

Response: Setup the Sphinx extension.


Instruction:
Write a Python 3 script for
fixing Django s manager appearance of some classes in autodoc. This avoids query evaluation.

Response:
def patch_django_for_autodoc():
    """Fix the appearance of some classes in autodoc.

    This avoids query evaluation.
    """
    # Fix Django's manager appearance
    ManagerDescriptor.__get__ = lambda self, *args, **kwargs: self.manager

    # Stop Django from executing DB queries
    models.QuerySet.__repr__ = lambda self: self.__class__.__name__


Instruction:
How would you code a function in Python 3 to
allow this package to be used as Sphinx extension. This is also called from the top-level ``__init__.py``. :type app: sphinx.application.Sphinx

Response:
def setup(app):
    """Allow this package to be used as Sphinx extension.
    This is also called from the top-level ``__init__.py``.

    :type app: sphinx.application.Sphinx
    """
    from .patches import patch_django_for_autodoc

    # When running, make sure Django doesn't execute querysets
    patch_django_for_autodoc()

    # Generate docstrings for Django model fields
    # Register the docstring processor with sphinx
    app.connect('autodoc-process-docstring', improve_model_docstring)

    # influence skip rules
    app.connect("autodoc-skip-member", autodoc_skip)


Instruction:
Can you generate the documentation for the following Python 3 function
def autodoc_skip(app, what, name, obj, skip, options):
    if name in config.EXCLUDE_MEMBERS:
        return True

    if name in config.INCLUDE_MEMBERS:
        return False

    return skip

Response: Hook that tells autodoc to skip certain fields.


Instruction:
Write a Python 3 script for
hooking that improves the autodoc docstrings for Django models.

Response:
def improve_model_docstring(app, what, name, obj, options, lines):
    """Hook that improves the autodoc docstrings for Django models.

    :type app: sphinx.application.Sphinx
    :param what: The parent type, ``class`` or ``module``
    :type what: str
    :param name: The dotted path to the child method/attribute.
    :type name: str
    :param obj: The Python object that i s being documented.
    :param options: The current autodoc settings.
    :type options: dict
    :param lines: The current documentation lines
    :type lines: list
    """
    if what == 'class':
        _improve_class_docs(app, obj, lines)
    elif what == 'attribute':
        _improve_attribute_docs(obj, name, lines)
    elif what == 'method':
        _improve_method_docs(obj, name, lines)

    # Return the extended docstring
    return lines


Instruction:
Can you implement a function in Python 3 that
improves the documentation of a class.

Response:
def _improve_class_docs(app, cls, lines):
    """Improve the documentation of a class."""
    if issubclass(cls, models.Model):
        _add_model_fields_as_params(app, cls, lines)
    elif issubclass(cls, forms.Form):
        _add_form_fields(cls, lines)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _add_model_fields_as_params(app, obj, lines):
    for field in obj._meta.get_fields():
        try:
            help_text = strip_tags(force_text(field.help_text))
            verbose_name = force_text(field.verbose_name).capitalize()
        except AttributeError:
            # e.g. ManyToOneRel
            continue

        # Add parameter
        if help_text:
            lines.append(u':param %s: %s' % (field.name, help_text))
        else:
            lines.append(u':param %s: %s' % (field.name, verbose_name))

        # Add type
        lines.append(_get_field_type(field))

    if 'sphinx.ext.inheritance_diagram' in app.extensions and \
            'sphinx.ext.graphviz' in app.extensions and \
            not any('inheritance-diagram::' in line for line in lines):
        lines.append('.. inheritance-diagram::')

Response: Improve the documentation of a Django model subclass.


Instruction:
How would you implement a function in Python 3 that
improves the documentation of a Django Form class.

Response:
def _add_form_fields(obj, lines):
    """Improve the documentation of a Django Form class.

    This highlights the available fields in the form.
    """
    lines.append("**Form fields:**")
    lines.append("")
    for name, field in obj.base_fields.items():
        field_type = "{}.{}".format(field.__class__.__module__, field.__class__.__name__)
        tpl = "* ``{name}``: {label} (:class:`~{field_type}`)"
        lines.append(tpl.format(
            name=name,
            field=field,
            label=field.label or name.replace('_', ' ').title(),
            field_type=field_type
        ))


Instruction:
Create a Python 3 function for
improving the documentation of various attributes.

Response:
def _improve_attribute_docs(obj, name, lines):
    """Improve the documentation of various attributes.
    This improves the navigation between related objects.

    :param obj: the instance of the object to document.
    :param name: full dotted path to the object.
    :param lines: expected documentation lines.
    """
    if obj is None:
        # Happens with form attributes.
        return

    if isinstance(obj, DeferredAttribute):
        # This only points to a field name, not a field.
        # Get the field by importing the name.
        cls_path, field_name = name.rsplit('.', 1)
        model = import_string(cls_path)
        field = model._meta.get_field(obj.field_name)

        del lines[:]  # lines.clear() is Python 3 only
        lines.append("**Model field:** {label}".format(
            label=field.verbose_name
        ))
    elif isinstance(obj, _FIELD_DESCRIPTORS):
        # These
        del lines[:]
        lines.append("**Model field:** {label}".format(
            label=obj.field.verbose_name
        ))

        if isinstance(obj, FileDescriptor):
            lines.append("**Return type:** :class:`~django.db.models.fields.files.FieldFile`")
        elif PhoneNumberDescriptor is not None and isinstance(obj, PhoneNumberDescriptor):
            lines.append("**Return type:** :class:`~phonenumber_field.phonenumber.PhoneNumber`")
    elif isinstance(obj, related_descriptors.ForwardManyToOneDescriptor):
        # Display a reasonable output for forward descriptors.
        related_model = obj.field.remote_field.model
        if isinstance(related_model, str):
            cls_path = related_model
        else:
            cls_path = "{}.{}".format(related_model.__module__, related_model.__name__)
        del lines[:]
        lines.append("**Model field:** {label}, "
                     "accesses the :class:`~{cls_path}` model.".format(
                         label=obj.field.verbose_name, cls_path=cls_path
                     ))
    elif isinstance(obj, related_descriptors.ReverseOneToOneDescriptor):
        related_model = obj.related.related_model
        if isinstance(related_model, str):
            cls_path = related_model
        else:
            cls_path = "{}.{}".format(related_model.__module__, related_model.__name__)
        del lines[:]
        lines.append("**Model field:** {label}, "
                     "accesses the :class:`~{cls_path}` model.".format(
                         label=obj.related.field.verbose_name, cls_path=cls_path
                     ))
    elif isinstance(obj, related_descriptors.ReverseManyToOneDescriptor):
        related_model = obj.rel.related_model
        if isinstance(related_model, str):
            cls_path = related_model
        else:
            cls_path = "{}.{}".format(related_model.__module__, related_model.__name__)
        del lines[:]
        lines.append("**Model field:** {label}, "
                     "accesses the M2M :class:`~{cls_path}` model.".format(
                         label=obj.field.verbose_name, cls_path=cls_path
                     ))
    elif isinstance(obj, (models.Manager, ManagerDescriptor)):
        # Somehow the 'objects' manager doesn't pass through the docstrings.
        module, cls_name, field_name = name.rsplit('.', 2)
        lines.append("Django manager to access the ORM")
        tpl = "Use ``{cls_name}.objects.all()`` to fetch all objects."
        lines.append(tpl.format(cls_name=cls_name))


Instruction:
Create a Python 3 function for
improving the documentation of various methods.

Response:
def _improve_method_docs(obj, name, lines):
    """Improve the documentation of various methods.

    :param obj: the instance of the method to document.
    :param name: full dotted path to the object.
    :param lines: expected documentation lines.
    """
    if not lines:
        # Not doing obj.__module__ lookups to avoid performance issues.
        if name.endswith('_display'):
            match = RE_GET_FOO_DISPLAY.search(name)
            if match is not None:
                # Django get_..._display method
                lines.append("**Autogenerated:** Shows the label of the :attr:`{field}`".format(
                    field=match.group('field')
                ))
        elif '.get_next_by_' in name:
            match = RE_GET_NEXT_BY.search(name)
            if match is not None:
                lines.append("**Autogenerated:** Finds next instance"
                             " based on :attr:`{field}`.".format(
                                 field=match.group('field')
                             ))
        elif '.get_previous_by_' in name:
            match = RE_GET_PREVIOUS_BY.search(name)
            if match is not None:
                lines.append("**Autogenerated:** Finds previous instance"
                             " based on :attr:`{field}`.".format(
                                 field=match.group('field')
                             ))


Instruction:
Can you implement a function in Python 3 that
returns annotated attribute names

Response:
def attr_names(cls) -> List[str]:
        """
        Returns annotated attribute names
        :return: List[str]
        """
        return [k for k, v in cls.attr_types().items()]


Instruction:
Make a summary of the following Python 3 code
def elliptic_fourier_descriptors(contour, order=10, normalize=False):
    dxy = np.diff(contour, axis=0)
    dt = np.sqrt((dxy ** 2).sum(axis=1))
    t = np.concatenate([([0., ]), np.cumsum(dt)])
    T = t[-1]

    phi = (2 * np.pi * t) / T

    coeffs = np.zeros((order, 4))
    for n in _range(1, order + 1):
        const = T / (2 * n * n * np.pi * np.pi)
        phi_n = phi * n
        d_cos_phi_n = np.cos(phi_n[1:]) - np.cos(phi_n[:-1])
        d_sin_phi_n = np.sin(phi_n[1:]) - np.sin(phi_n[:-1])
        a_n = const * np.sum((dxy[:, 0] / dt) * d_cos_phi_n)
        b_n = const * np.sum((dxy[:, 0] / dt) * d_sin_phi_n)
        c_n = const * np.sum((dxy[:, 1] / dt) * d_cos_phi_n)
        d_n = const * np.sum((dxy[:, 1] / dt) * d_sin_phi_n)
        coeffs[n - 1, :] = a_n, b_n, c_n, d_n

    if normalize:
        coeffs = normalize_efd(coeffs)

    return coeffs

Response: Calculate the elliptical Fourier coefficients for a contour array.


Instruction:
Given the following Python 3 function, write the documentation
def normalize_efd(coeffs, size_invariant=True):
    # Make the coefficients have a zero phase shift from
    # the first major axis. Theta_1 is that shift angle.
    theta_1 = 0.5 * np.arctan2(
        2 * ((coeffs[0, 0] * coeffs[0, 1]) + (coeffs[0, 2] * coeffs[0, 3])),
        ((coeffs[0, 0] ** 2) - (coeffs[0, 1] ** 2) + (coeffs[0, 2] ** 2) - (coeffs[0, 3] ** 2)))
    # Rotate all coefficients by theta_1.
    for n in _range(1, coeffs.shape[0] + 1):
        coeffs[n - 1, :] = np.dot(
            np.array([[coeffs[n - 1, 0], coeffs[n - 1, 1]],
                      [coeffs[n - 1, 2], coeffs[n - 1, 3]]]),
            np.array([[np.cos(n * theta_1), -np.sin(n * theta_1)],
                      [np.sin(n * theta_1), np.cos(n * theta_1)]])).flatten()

    # Make the coefficients rotation invariant by rotating so that
    # the semi-major axis is parallel to the x-axis.
    psi_1 = np.arctan2(coeffs[0, 2], coeffs[0, 0])
    psi_rotation_matrix = np.array([[np.cos(psi_1), np.sin(psi_1)],
                                    [-np.sin(psi_1), np.cos(psi_1)]])
    # Rotate all coefficients by -psi_1.
    for n in _range(1, coeffs.shape[0] + 1):
        coeffs[n - 1, :] = psi_rotation_matrix.dot(
            np.array([[coeffs[n - 1, 0], coeffs[n - 1, 1]],
                      [coeffs[n - 1, 2], coeffs[n - 1, 3]]])).flatten()

    if size_invariant:
        # Obtain size-invariance by normalizing.
        coeffs /= np.abs(coeffs[0, 0])

    return coeffs

Response: Normalizes an array of Fourier coefficients.


Instruction:
How would you implement a function in Python 3 that
calculates the A_0 and C_0 coefficients of the elliptic Fourier series.

Response:
def calculate_dc_coefficients(contour):
    """Calculate the :math:`A_0` and :math:`C_0` coefficients of the elliptic Fourier series.

    :param numpy.ndarray contour: A contour array of size ``[M x 2]``.
    :return: The :math:`A_0` and :math:`C_0` coefficients.
    :rtype: tuple

    """
    dxy = np.diff(contour, axis=0)
    dt = np.sqrt((dxy ** 2).sum(axis=1))
    t = np.concatenate([([0., ]), np.cumsum(dt)])
    T = t[-1]

    xi = np.cumsum(dxy[:, 0]) - (dxy[:, 0] / dt) * t[1:]
    A0 = (1 / T) * np.sum(((dxy[:, 0] / (2 * dt)) * np.diff(t ** 2)) + xi * dt)
    delta = np.cumsum(dxy[:, 1]) - (dxy[:, 1] / dt) * t[1:]
    C0 = (1 / T) * np.sum(((dxy[:, 1] / (2 * dt)) * np.diff(t ** 2)) + delta * dt)

    # A0 and CO relate to the first point of the contour array as origin.
    # Adding those values to the coefficients to make them relate to true origin.
    return contour[0, 0] + A0, contour[0, 1] + C0


Instruction:
Implement a Python 3 function for
plotting a grid of successive truncations of the Fourier coefficients.

Response:
def plot_efd(coeffs, locus=(0., 0.), image=None, contour=None, n=300):
    """Plot a ``[2 x (N / 2)]`` grid of successive truncations of the series.

    .. note::

        Requires `matplotlib <http://matplotlib.org/>`_!

    :param numpy.ndarray coeffs: ``[N x 4]`` Fourier coefficient array.
    :param list, tuple or numpy.ndarray locus:
        The :math:`A_0` and :math:`C_0` elliptic locus in [#a]_ and [#b]_.
    :param int n: Number of points to use for plotting of Fourier series.

    """
    try:
        import matplotlib.pyplot as plt
    except ImportError:
        print("Cannot plot: matplotlib was not installed.")
        return

    N = coeffs.shape[0]
    N_half = int(np.ceil(N / 2))
    n_rows = 2

    t = np.linspace(0, 1.0, n)
    xt = np.ones((n,)) * locus[0]
    yt = np.ones((n,)) * locus[1]

    for n in _range(coeffs.shape[0]):
        xt += (coeffs[n, 0] * np.cos(2 * (n + 1) * np.pi * t)) + \
              (coeffs[n, 1] * np.sin(2 * (n + 1) * np.pi * t))
        yt += (coeffs[n, 2] * np.cos(2 * (n + 1) * np.pi * t)) + \
              (coeffs[n, 3] * np.sin(2 * (n + 1) * np.pi * t))
        ax = plt.subplot2grid((n_rows, N_half), (n // N_half, n % N_half))
        ax.set_title(str(n + 1))
        if contour is not None:
            ax.plot(contour[:, 1], contour[:, 0], 'c--', linewidth=2)
        ax.plot(yt, xt, 'r', linewidth=2)
        if image is not None:
            ax.imshow(image, plt.cm.gray)

    plt.show()


Instruction:
How would you explain what the following Python 3 function does
def _errcheck(result, func, arguments):

    if result != 0:
        raise XdoException(
            'Function {0} returned error code {1}'
            .format(func.__name__, result))
    return None

Response: Error checker for functions returning an integer indicating that the function returned an error code.


Instruction:
How would you code a function in Python 3 to
generate input mask from bytemask

Response:
def _gen_input_mask(mask):
    """Generate input mask from bytemask"""
    return input_mask(
        shift=bool(mask & MOD_Shift),
        lock=bool(mask & MOD_Lock),
        control=bool(mask & MOD_Control),
        mod1=bool(mask & MOD_Mod1),
        mod2=bool(mask & MOD_Mod2),
        mod3=bool(mask & MOD_Mod3),
        mod4=bool(mask & MOD_Mod4),
        mod5=bool(mask & MOD_Mod5))


Instruction:
Write a Python 3 script to
move the mouse to a specific location.

Response:
def move_mouse(self, x, y, screen=0):
        """
        Move the mouse to a specific location.

        :param x: the target X coordinate on the screen in pixels.
        :param y: the target Y coordinate on the screen in pixels.
        :param screen: the screen (number) you want to move on.
        """
        # todo: apparently the "screen" argument is not behaving properly
        #       and sometimes even making the interpreter crash..
        #       Figure out why (changed API / using wrong header?)

        # >>> xdo.move_mouse(3000,200,1)

        # X Error of failed request:  BadWindow (invalid Window parameter)
        #   Major opcode of failed request:  41 (X_WarpPointer)
        #   Resource id in failed request:  0x2a4fca0
        #   Serial number of failed request:  25
        #   Current serial number in output stream:  26

        # Just to be safe..
        # screen = 0

        x = ctypes.c_int(x)
        y = ctypes.c_int(y)
        screen = ctypes.c_int(screen)

        _libxdo.xdo_move_mouse(self._xdo, x, y, screen)


Instruction:
Can you tell what is the following Python 3 function doing
def move_mouse_relative_to_window(self, window, x, y):
        _libxdo.xdo_move_mouse_relative_to_window(
            self._xdo, ctypes.c_ulong(window), x, y)

Response: Move the mouse to a specific location relative to the top - left corner of a window.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def move_mouse_relative(self, x, y):
        _libxdo.xdo_move_mouse_relative(self._xdo, x, y)

Response: Move the mouse relative to the current position.


Instruction:
How would you explain what the following Python 3 function does
def mouse_down(self, window, button):
        _libxdo.xdo_mouse_down(
            self._xdo, ctypes.c_ulong(window), ctypes.c_int(button))

Response: Send a mouse down event for a given button.


Instruction:
Implement a function in Python 3 to
send a mouse release for a given button.

Response:
def mouse_up(self, window, button):
        """
        Send a mouse release (aka mouse up) for a given button at
        the current mouse location.

        :param window:
            The window you want to send the event to or CURRENTWINDOW
        :param button:
            The mouse button. Generally, 1 is left, 2 is middle, 3 is
            right, 4 is wheel up, 5 is wheel down.
        """
        _libxdo.xdo_mouse_up(
            self._xdo, ctypes.c_ulong(window), ctypes.c_int(button))


Instruction:
Can you create a Python 3 function that
gets the current mouse location.

Response:
def get_mouse_location(self):
        """
        Get the current mouse location (coordinates and screen number).

        :return: a namedtuple with ``x``, ``y`` and ``screen_num`` fields
        """
        x = ctypes.c_int(0)
        y = ctypes.c_int(0)
        screen_num = ctypes.c_int(0)
        _libxdo.xdo_get_mouse_location(
            self._xdo, ctypes.byref(x), ctypes.byref(y),
            ctypes.byref(screen_num))
        return mouse_location(x.value, y.value, screen_num.value)


Instruction:
Write a Python 3 function that can
get the window the mouse is currently over.

Response:
def get_window_at_mouse(self):
        """
        Get the window the mouse is currently over
        """
        window_ret = ctypes.c_ulong(0)
        _libxdo.xdo_get_window_at_mouse(self._xdo, ctypes.byref(window_ret))
        return window_ret.value


Instruction:
Can you generate the documentation for the following Python 3 function
def get_mouse_location2(self):
        x = ctypes.c_int(0)
        y = ctypes.c_int(0)
        screen_num_ret = ctypes.c_ulong(0)
        window_ret = ctypes.c_ulong(0)
        _libxdo.xdo_get_mouse_location2(
            self._xdo, ctypes.byref(x), ctypes.byref(y),
            ctypes.byref(screen_num_ret), ctypes.byref(window_ret))
        return mouse_location2(x.value, y.value, screen_num_ret.value,
                               window_ret.value)

Response: Get all mouse location - related data.


Instruction:
Implement a Python 3 function for
waiting for the mouse to move from a location.

Response:
def wait_for_mouse_move_from(self, origin_x, origin_y):
        """
        Wait for the mouse to move from a location. This function will block
        until the condition has been satisified.

        :param origin_x: the X position you expect the mouse to move from
        :param origin_y: the Y position you expect the mouse to move from
        """
        _libxdo.xdo_wait_for_mouse_move_from(self._xdo, origin_x, origin_y)


Instruction:
Can you tell what is the following Python 3 function doing
def wait_for_mouse_move_to(self, dest_x, dest_y):
        _libxdo.xdo_wait_for_mouse_move_from(self._xdo, dest_x, dest_y)

Response: Wait for the mouse to move to a location.


Instruction:
Here you have a function in Python 3, explain what it does
def click_window(self, window, button):
        _libxdo.xdo_click_window(self._xdo, window, button)

Response: Send a click for a specific mouse button at the current mouse location.


Instruction:
Can you create a Python 3 function that
sends a one or more clicks for a specific mouse button at the current mouse location.

Response:
def click_window_multiple(self, window, button, repeat=2, delay=100000):
        """
        Send a one or more clicks for a specific mouse button at the
        current mouse location.

        :param window:
            The window you want to send the event to or CURRENTWINDOW
        :param button:
            The mouse button. Generally, 1 is left, 2 is middle, 3 is
            right, 4 is wheel up, 5 is wheel down.
        :param repeat: number of repetitions (default: 2)
        :param delay: delay between clicks, in microseconds (default: 100k)
        """
        _libxdo.xdo_click_window_multiple(
            self._xdo, window, button, repeat, delay)


Instruction:
How would you explain what the following Python 3 function does
def enter_text_window(self, window, string, delay=12000):
        return _libxdo.xdo_enter_text_window(self._xdo, window, string, delay)

Response: Enter a string to the specified window.


Instruction:
How would you implement a function in Python 3 that
sends a keysequence to the specified window.

Response:
def send_keysequence_window(self, window, keysequence, delay=12000):
        """
        Send a keysequence to the specified window.

        This allows you to send keysequences by symbol name. Any combination
        of X11 KeySym names separated by '+' are valid. Single KeySym names
        are valid, too.

        Examples:
          "l"
          "semicolon"
          "alt+Return"
          "Alt_L+Tab"

        If you want to type a string, such as "Hello world." you want to
        instead use xdo_enter_text_window.

        :param window: The window you want to send the keysequence to or
          CURRENTWINDOW
        :param keysequence: The string keysequence to send.
        :param delay: The delay between keystrokes in microseconds.
        """
        _libxdo.xdo_send_keysequence_window(
            self._xdo, window, keysequence, delay)


Instruction:
Implement a Python 3 function for
sending key release up events for the given key sequence.

Response:
def send_keysequence_window_up(self, window, keysequence, delay=12000):
        """Send key release (up) events for the given key sequence"""
        _libxdo.xdo_send_keysequence_window_up(
            self._xdo, window, keysequence, ctypes.c_ulong(delay))


Instruction:
How would you implement a function in Python 3 that
sends key press ( down ) events for the given key sequence.

Response:
def send_keysequence_window_down(self, window, keysequence, delay=12000):
        """Send key press (down) events for the given key sequence"""
        _libxdo.xdo_send_keysequence_window_down(
            self._xdo, window, keysequence, ctypes.c_ulong(delay))


Instruction:
How would you explain what the following Python 3 function does
def send_keysequence_window_list_do(
            self, window, keys, pressed=1, modifier=None, delay=120000):
        """
        Send a series of keystrokes.

        :param window: The window to send events to or CURRENTWINDOW
        :param keys: The array of charcodemap_t entities to send.
        :param pressed: 1 for key press, 0 for key release.
        :param modifier:
            Pointer to integer to record the modifiers
            activated by the keys being pressed. If NULL, we don't save
            the modifiers.
        :param delay:
            The delay between keystrokes in microseconds.
        """
        # todo: how to properly use charcodes_t in a nice way?
        _libxdo.xdo_send_keysequence_window_list_do(
            self._xdo, window, keys, len(keys), pressed, modifier, delay)

Response: Send a series of keystrokes to a specific window.


Instruction:
How would you explain what the following Python 3 function does
def get_active_keys_to_keycode_list(self):

        try:
            _libxdo.xdo_get_active_keys_to_keycode_list
        except AttributeError:
            # Apparently, this was implemented in a later version..
            raise NotImplementedError()

        keys = POINTER(charcodemap_t)
        nkeys = ctypes.c_int(0)
        _libxdo.xdo_get_active_keys_to_keycode_list(
            self._xdo, ctypes.byref(keys), ctypes.byref(nkeys))

        # todo: make sure this returns a list of charcodemap_t!
        return keys.value

Response: Get a list of active keys. Uses XQueryKeymap


Instruction:
Write a Python 3 function that can
wait for a window to have a specific map state.

Response:
def wait_for_window_map_state(self, window, state):
        """
        Wait for a window to have a specific map state.

        State possibilities:
          IsUnmapped - window is not displayed.
          IsViewable - window is mapped and shown (though may be
              clipped by windows on top of it)
          IsUnviewable - window is mapped but a parent window is unmapped.

        :param window: the window you want to wait for.
        :param state: the state to wait for.
        """
        _libxdo.xdo_wait_for_window_map_state(self._xdo, window, state)


Instruction:
Write a Python 3 function for
moving a window to a specific location.

Response:
def move_window(self, window, x, y):
        """
        Move a window to a specific location.

        The top left corner of the window will be moved to the x,y coordinate.

        :param wid: the window to move
        :param x: the X coordinate to move to.
        :param y: the Y coordinate to move to.
        """
        _libxdo.xdo_move_window(self._xdo, window, x, y)


Instruction:
Explain what the following Python 3 code does
def translate_window_with_sizehint(self, window, width, height):
        width_ret = ctypes.c_uint(0)
        height_ret = ctypes.c_uint(0)
        _libxdo.xdo_translate_window_with_sizehint(
            self._xdo, window, width, height,
            ctypes.byref(width_ret),
            ctypes.byref(height_ret))
        return width_ret.value, height_ret.value

Response: This function will apply a window sizing hints to a given width and height.


Instruction:
Explain what the following Python 3 code does
def set_window_size(self, window, w, h, flags=0):
        _libxdo.xdo_set_window_size(self._xdo, window, w, h, flags)

Response: Change the size of a window.


Instruction:
Implement a function in Python 3 to
change a window property.

Response:
def set_window_property(self, window, name, value):
        """
        Change a window property.

        Example properties you can change are WM_NAME, WM_ICON_NAME, etc.

        :param wid: The window to change a property of.
        :param name: the string name of the property.
        :param value: the string value of the property.
        """
        _libxdo.xdo_set_window_property(self._xdo, window, name, value)


Instruction:
Create a Python 3 function for
changing the classname and or class.

Response:
def set_window_class(self, window, name, class_):
        """
        Change the window's classname and or class.

        :param name: The new class name. If ``None``, no change.
        :param class_: The new class. If ``None``, no change.
        """
        _libxdo.xdo_set_window_class(self._xdo, window, name, class_)


Instruction:
Here you have a function in Python 3, explain what it does
def set_window_urgency(self, window, urgency):
        _libxdo.xdo_set_window_urgency(self._xdo, window, urgency)

Response: Sets the urgency hint for a window.


Instruction:
How would you explain what the following Python 3 function does
def set_window_override_redirect(self, window, override_redirect):
        _libxdo.xdo_set_window_override_redirect(
            self._xdo, window, override_redirect)

Response: Set the override_redirect value for a window.


Instruction:
Here you have a function in Python 3, explain what it does
def get_focused_window(self):
        window_ret = window_t(0)
        _libxdo.xdo_get_focused_window(self._xdo, ctypes.byref(window_ret))
        return window_ret.value

Response: Get the currently - focused window.


Instruction:
How would you code a function in Python 3 to
wait for a window to have or lose focus.

Response:
def wait_for_window_focus(self, window, want_focus):
        """
        Wait for a window to have or lose focus.

        :param window: The window to wait on
        :param want_focus: If 1, wait for focus. If 0, wait for loss of focus.
        """
        _libxdo.xdo_wait_for_window_focus(self._xdo, window, want_focus)


Instruction:
Make a summary of the following Python 3 code
def get_focused_window_sane(self):
        window_ret = window_t(0)
        _libxdo.xdo_get_focused_window_sane(
            self._xdo, ctypes.byref(window_ret))
        return window_ret.value

Response:
Like xdo_get_focused_window but return the first ancestor - or - self
           .


Instruction:
Write a Python 3 script for
waiting for a window to be active or not active.

Response:
def wait_for_window_active(self, window, active=1):
        """
        Wait for a window to be active or not active.

        Requires your window manager to support this.
        Uses _NET_ACTIVE_WINDOW from the EWMH spec.

        :param window: the window to wait on
        :param active: If 1, wait for active. If 0, wait for inactive.
        """
        _libxdo.xdo_wait_for_window_active(self._xdo, window, active)


Instruction:
Write a Python 3 script for
getting a window s location.

Response:
def get_window_location(self, window):
        """
        Get a window's location.
        """
        screen_ret = Screen()
        x_ret = ctypes.c_int(0)
        y_ret = ctypes.c_int(0)
        _libxdo.xdo_get_window_location(
            self._xdo, window, ctypes.byref(x_ret), ctypes.byref(y_ret),
            ctypes.byref(screen_ret))
        return window_location(x_ret.value, y_ret.value, screen_ret)


Instruction:
Can you create a Python 3 function that
gets a window s size.

Response:
def get_window_size(self, window):
        """
        Get a window's size.
        """
        w_ret = ctypes.c_uint(0)
        h_ret = ctypes.c_uint(0)
        _libxdo.xdo_get_window_size(self._xdo, window, ctypes.byref(w_ret),
                                    ctypes.byref(h_ret))
        return window_size(w_ret.value, h_ret.value)


Instruction:
Write a Python 3 script to
get the currently - active window.

Response:
def get_active_window(self):
        """
        Get the currently-active window.
        Requires your window manager to support this.
        Uses ``_NET_ACTIVE_WINDOW`` from the EWMH spec.
        """
        window_ret = window_t(0)
        _libxdo.xdo_get_active_window(self._xdo, ctypes.byref(window_ret))
        return window_ret.value


Instruction:
Write a Python 3 script for
selecting a window ID by clicking on it.

Response:
def select_window_with_click(self):
        """
        Get a window ID by clicking on it.
        This function blocks until a selection is made.
        """
        window_ret = window_t(0)
        _libxdo.xdo_select_window_with_click(
            self._xdo, ctypes.byref(window_ret))
        return window_ret.value


Instruction:
Given the following Python 3 function, write the documentation
def get_number_of_desktops(self):
        ndesktops = ctypes.c_long(0)
        _libxdo.xdo_get_number_of_desktops(self._xdo, ctypes.byref(ndesktops))
        return ndesktops.value

Response: Get the current number of desktops.


Instruction:
Can you tell what is the following Python 3 function doing
def get_current_desktop(self):
        desktop = ctypes.c_long(0)
        _libxdo.xdo_get_current_desktop(self._xdo, ctypes.byref(desktop))
        return desktop.value

Response: Get the current desktop.


Instruction:
Here you have a function in Python 3, explain what it does
def set_desktop_for_window(self, window, desktop):
        _libxdo.xdo_set_desktop_for_window(self._xdo, window, desktop)

Response: Move a window to another desktop


Instruction:
Make a summary of the following Python 3 code
def get_desktop_for_window(self, window):
        desktop = ctypes.c_long(0)
        _libxdo.xdo_get_desktop_for_window(
            self._xdo, window, ctypes.byref(desktop))
        return desktop.value

Response: Get the desktop a window is on.


Instruction:
Can you generate the documentation for the following Python 3 function
def search_windows(
            self, winname=None, winclass=None, winclassname=None,
            pid=None, only_visible=False, screen=None, require=False,
            searchmask=0, desktop=None, limit=0, max_depth=-1):
        """
        Search for windows.

        :param winname:
            Regexp to be matched against window name
        :param winclass:
            Regexp to be matched against window class
        :param winclassname:
            Regexp to be matched against window class name
        :param pid:
            Only return windows from this PID
        :param only_visible:
            If True, only return visible windows
        :param screen:
            Search only windows on this screen
        :param require:
            If True, will match ALL conditions. Otherwise, windows matching
            ANY condition will be returned.
        :param searchmask:
            Search mask, for advanced usage. Leave this alone if you
            don't kwnow what you are doing.
        :param limit:
            Maximum number of windows to list. Zero means no limit.
        :param max_depth:
            Maximum depth to return. Defaults to -1, meaning "no limit".
        :return:
            A list of window ids matching query.
        """
        windowlist_ret = ctypes.pointer(window_t(0))
        nwindows_ret = ctypes.c_uint(0)

        search = xdo_search_t(searchmask=searchmask)

        if winname is not None:
            search.winname = winname
            search.searchmask |= SEARCH_NAME

        if winclass is not None:
            search.winclass = winclass
            search.searchmask |= SEARCH_CLASS

        if winclassname is not None:
            search.winclassname = winclassname
            search.searchmask |= SEARCH_CLASSNAME

        if pid is not None:
            search.pid = pid
            search.searchmask |= SEARCH_PID

        if only_visible:
            search.only_visible = True
            search.searchmask |= SEARCH_ONLYVISIBLE

        if screen is not None:
            search.screen = screen
            search.searchmask |= SEARCH_SCREEN

        if screen is not None:
            search.screen = desktop
            search.searchmask |= SEARCH_DESKTOP

        search.limit = limit
        search.max_depth = max_depth

        _libxdo.xdo_search_windows(
            self._xdo, search,
            ctypes.byref(windowlist_ret),
            ctypes.byref(nwindows_ret))

        return [windowlist_ret[i] for i in range(nwindows_ret.value)]

Response: Search for windows in the current process.


Instruction:
Explain what the following Python 3 code does
def get_symbol_map(self):
        # todo: make sure we return a list of strings!
        sm = _libxdo.xdo_get_symbol_map()

        # Return value is like:
        # ['alt', 'Alt_L', ..., None, None, None, ...]
        # We want to return only values up to the first None.
        # todo: any better solution than this?
        i = 0
        ret = []
        while True:
            c = sm[i]
            if c is None:
                return ret
            ret.append(c)
            i += 1

Response: Get the symbol map for the current set of tokens.


Instruction:
Write a Python 3 script to
get a list of active keys. Uses XQueryKeymap.

Response:
def get_active_modifiers(self):
        """
        Get a list of active keys. Uses XQueryKeymap.

        :return: list of charcodemap_t instances
        """
        keys = ctypes.pointer(charcodemap_t())
        nkeys = ctypes.c_int(0)

        _libxdo.xdo_get_active_modifiers(
            self._xdo, ctypes.byref(keys), ctypes.byref(nkeys))
        return [keys[i] for i in range(nkeys.value)]


Instruction:
Can you create a Python 3 function that
gets a window s name if any.

Response:
def get_window_name(self, win_id):
        """
        Get a window's name, if any.
        """
        window = window_t(win_id)
        name_ptr = ctypes.c_char_p()
        name_len = ctypes.c_int(0)
        name_type = ctypes.c_int(0)
        _libxdo.xdo_get_window_name(
            self._xdo, window, ctypes.byref(name_ptr),
            ctypes.byref(name_len), ctypes.byref(name_type))
        name = name_ptr.value
        _libX11.XFree(name_ptr)  # Free the string allocated by Xlib
        return name


Instruction:
Write a Python 3 script for
importing all the given modules

Response:
def import_metadata(module_paths):
    """Import all the given modules"""
    cwd = os.getcwd()
    if cwd not in sys.path:
        sys.path.insert(0, cwd)
    modules = []
    try:
        for path in module_paths:
            modules.append(import_module(path))
    except ImportError as e:
        err = RuntimeError('Could not import {}: {}'.format(path, str(e)))
        raise_from(err, e)
    return modules


Instruction:
Create a Python 3 function for
loading JSON metadata from opened stream.

Response:
def load_metadata(stream):
    """Load JSON metadata from opened stream."""
    try:
        metadata = json.load(
            stream, encoding='utf8', object_pairs_hook=OrderedDict)
    except json.JSONDecodeError as e:
        err = RuntimeError('Error parsing {}: {}'.format(stream.name, e))
        raise_from(err, e)
    else:
        # convert changelog keys back to ints for sorting
        for group in metadata:
            if group == '$version':
                continue
            apis = metadata[group]['apis']
            for api in apis.values():
                int_changelog = OrderedDict()
                for version, log in api.get('changelog', {}).items():
                    int_changelog[int(version)] = log
                api['changelog'] = int_changelog
    finally:
        stream.close()

    return metadata


Instruction:
Can you tell what is the following Python 3 function doing
def strip_punctuation_space(value):
    "Strip excess whitespace prior to punctuation."
    def strip_punctuation(string):
        replacement_list = (
            (' .',  '.'),
            (' :',  ':'),
            ('( ',  '('),
            (' )',  ')'),
        )
        for match, replacement in replacement_list:
            string = string.replace(match, replacement)
        return string
    if value == None:
        return None
    if type(value) == list:
        return [strip_punctuation(v) for v in value]
    return strip_punctuation(value)

Response: Strip excess whitespace prior to punctuation.


Instruction:
Create a Python 3 function to
concatenate two sentences together with punctuation glue

Response:
def join_sentences(string1, string2, glue='.'):
    "concatenate two sentences together with punctuation glue"
    if not string1 or string1 == '':
        return string2
    if not string2 or string2 == '':
        return string1
    # both are strings, continue joining them together with the glue and whitespace
    new_string = string1.rstrip()
    if not new_string.endswith(glue):
        new_string += glue
    new_string += ' ' + string2.lstrip()
    return new_string


Instruction:
Can you create a Python 3 function that
attempts to cast given value to an integer if failed return the original value if failed.

Response:
def coerce_to_int(val, default=0xDEADBEEF):
    """Attempts to cast given value to an integer, return the original value if failed or the default if one provided."""
    try:
        return int(val)
    except (TypeError, ValueError):
        if default != 0xDEADBEEF:
            return default
        return val


Instruction:
Explain what the following Python 3 code does
def nullify(function):
    "Decorator. If empty list, returns None, else list."
    def wrapper(*args, **kwargs):
        value = function(*args, **kwargs)
        if(type(value) == list and len(value) == 0):
            return None
        return value
    return wrapper

Response: Decorator. If empty list returns None else list.


Instruction:
Can you tell what is the following Python 3 function doing
def inten(function):
    "Decorator. Attempts to convert return value to int"
    def wrapper(*args, **kwargs):
        return coerce_to_int(function(*args, **kwargs))
    return wrapper

Response: Decorator. Attempts to convert return value to int


Instruction:
Write a Python 3 script to
give a year month and day numeric values and a timezone returns a structured date object.

Response:
def date_struct(year, month, day, tz = "UTC"):
    """
    Given year, month and day numeric values and a timezone
    convert to structured date object
    """
    ymdtz = (year, month, day, tz)
    if None in ymdtz:
        #logger.debug("a year, month, day or tz value was empty: %s" % str(ymdtz))
        return None # return early if we have a bad value
    try:
        return time.strptime("%s-%s-%s %s" % ymdtz,  "%Y-%m-%d %Z")
    except(TypeError, ValueError):
        #logger.debug("date failed to convert: %s" % str(ymdtz))
        pass


Instruction:
Can you generate the documentation for the following Python 3 function
def date_struct_nn(year, month, day, tz="UTC"):
    if not day:
        day = 1
    if not month:
        month = 1
    return date_struct(year, month, day, tz)

Response: Assemble a date object but set it to 1 if none is set it to 1 if none is set it to 1 if none is set it to 1 if none is set it to 1 if none is set it to 1 if none is set it to 1 if none is set it to 1 if none is set it to 1 if none is set


Instruction:
Can you write a function in Python 3 where it
strips the uri schema from the start of DOI URL strings

Response:
def doi_uri_to_doi(value):
    "Strip the uri schema from the start of DOI URL strings"
    if value is None:
        return value
    replace_values = ['http://dx.doi.org/', 'https://dx.doi.org/',
                      'http://doi.org/', 'https://doi.org/']
    for replace_value in replace_values:
        value = value.replace(replace_value, '')
    return value


Instruction:
How would you implement a function in Python 3 that
gives a list of tags only return those whose text doesn t start with DOI :

Response:
def remove_doi_paragraph(tags):
    "Given a list of tags, only return those whose text doesn't start with 'DOI:'"
    p_tags = list(filter(lambda tag: not starts_with_doi(tag), tags))
    p_tags = list(filter(lambda tag: not paragraph_is_only_doi(tag), p_tags))
    return p_tags


Instruction:
Can you implement a function in Python 3 that
strips the uri schema from the start of ORCID URL strings

Response:
def orcid_uri_to_orcid(value):
    "Strip the uri schema from the start of ORCID URL strings"
    if value is None:
        return value
    replace_values = ['http://orcid.org/', 'https://orcid.org/']
    for replace_value in replace_values:
        value = value.replace(replace_value, '')
    return value


Instruction:
Here you have a function in Python 3, explain what it does
def component_acting_parent_tag(parent_tag, tag):
    if parent_tag.name == "fig-group":
        if (len(tag.find_previous_siblings("fig")) > 0):
            acting_parent_tag = first(extract_nodes(parent_tag, "fig"))
        else:
            # Do not return the first fig as parent of itself
            return None
    else:
        acting_parent_tag = parent_tag
    return acting_parent_tag

Response: Return the parent tag of the given tag.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def extract_nodes(soup, nodename, attr = None, value = None):
    tags = soup.find_all(nodename)
    if attr != None and value != None:
        return list(filter(lambda tag: tag.get(attr) == value, tags))
    return list(tags)

Response: Returns a list of tags from the given soup matching the given nodename.


Instruction:
Write a Python 3 function that can
return the contents of a tag including it s children as a string.

Response:
def node_contents_str(tag):
    """
    Return the contents of a tag, including it's children, as a string.
    Does not include the root/parent of the tag.
    """
    if not tag:
        return None
    tag_string = ''
    for child_tag in tag.children:
        if isinstance(child_tag, Comment):
            # BeautifulSoup does not preserve comment tags, add them back
            tag_string += '<!--%s-->' % unicode_value(child_tag)
        else:
            tag_string += unicode_value(child_tag)
    return tag_string if tag_string != '' else None


Instruction:
Write a Python 3 function that can
give a beautiful soup tag look at its parents and return the first parent tag that matches nodename or the list nodename

Response:
def first_parent(tag, nodename):
    """
    Given a beautiful soup tag, look at its parents and return the first
    tag name that matches nodename or the list nodename
    """
    if nodename is not None and type(nodename) == str:
        nodename = [nodename]
    return first(list(filter(lambda tag: tag.name in nodename, tag.parents)))


Instruction:
Write a Python 3 function for
returning the ordinal of the figure in which the given tag is for a main figure or a child figure.

Response:
def tag_fig_ordinal(tag):
    """
    Meant for finding the position of fig tags with respect to whether
    they are for a main figure or a child figure
    """
    tag_count = 0
    if 'specific-use' not in tag.attrs:
        # Look for tags with no "specific-use" attribute
        return len(list(filter(lambda tag: 'specific-use' not in tag.attrs,
                          tag.find_all_previous(tag.name)))) + 1


Instruction:
How would you code a function in Python 3 to
count the number of media tags that are sibling of the given tag.

Response:
def tag_media_sibling_ordinal(tag):
    """
    Count sibling ordinal differently depending on if the
    mimetype is video or not
    """
    if hasattr(tag, 'name') and tag.name != 'media':
        return None

    nodenames = ['fig','supplementary-material','sub-article']
    first_parent_tag = first_parent(tag, nodenames)

    sibling_ordinal = None

    if first_parent_tag:
        # Start counting at 0
        sibling_ordinal = 0
        for media_tag in first_parent_tag.find_all(tag.name):
            if 'mimetype' in tag.attrs and tag['mimetype'] == 'video':
                # Count all video type media tags
                if 'mimetype' in media_tag.attrs and tag['mimetype'] == 'video':
                    sibling_ordinal += 1
                if media_tag == tag:
                    break

            else:
                # Count all non-video type media tags
                if (('mimetype' not in media_tag.attrs)
                    or ('mimetype' in media_tag.attrs and tag['mimetype'] != 'video')):
                    sibling_ordinal += 1
                if media_tag == tag:
                    break
    else:
        # Start counting at 1
        sibling_ordinal = 1
        for prev_tag in tag.find_all_previous(tag.name):
            if not first_parent(prev_tag, nodenames):
                if 'mimetype' in tag.attrs and tag['mimetype'] == 'video':
                    # Count all video type media tags
                    if supp_asset(prev_tag) == supp_asset(tag) and 'mimetype' in prev_tag.attrs:
                        sibling_ordinal += 1
                else:
                    if supp_asset(prev_tag) == supp_asset(tag) and 'mimetype' not in prev_tag.attrs:
                        sibling_ordinal += 1

    return sibling_ordinal


Instruction:
Can you tell what is the following Python 3 function doing
def tag_supplementary_material_sibling_ordinal(tag):
    if hasattr(tag, 'name') and tag.name != 'supplementary-material':
        return None

    nodenames = ['fig','media','sub-article']
    first_parent_tag = first_parent(tag, nodenames)

    sibling_ordinal = 1

    if first_parent_tag:
        # Within the parent tag of interest, count the tags
        #  having the same asset value
        for supp_tag in first_parent_tag.find_all(tag.name):
            if tag == supp_tag:
                # Stop once we reach the same tag we are checking
                break
            if supp_asset(supp_tag) == supp_asset(tag):
                sibling_ordinal += 1

    else:
        # Look in all previous elements that do not have a parent
        #  and count the tags having the same asset value
        for prev_tag in tag.find_all_previous(tag.name):
            if not first_parent(prev_tag, nodenames):
                if supp_asset(prev_tag) == supp_asset(tag):
                    sibling_ordinal += 1

    return sibling_ordinal

Response: Return the ordinal of the supplementary - material tag that is the position inside any parent tag that has the same asset value to get its sibling ordinal.


Instruction:
Write a Python 3 function that can
give a supplementary - material tag returns the asset value

Response:
def supp_asset(tag):
    """
    Given a supplementary-material tag, the asset value depends on
    its label text. This also informs in what order (its ordinal) it
    has depending on how many of each type is present
    """
    # Default
    asset = 'supp'
    if first(extract_nodes(tag, "label")):
        label_text = node_text(first(extract_nodes(tag, "label"))).lower()
        # Keyword match the label
        if label_text.find('code') > 0:
            asset = 'code'
        elif label_text.find('data') > 0:
            asset = 'data'
    return asset


Instruction:
Can you generate a brief explanation for the following Python 3 code
def text_to_title(value):
    title = None
    if not value:
        return title
    words = value.split(" ")
    keep_words = []
    for word in words:
        if word.endswith(".") or word.endswith(":"):
            keep_words.append(word)
            if len(word) > 1 and "<italic>" not in word and "<i>" not in word:
                break
        else:
            keep_words.append(word)
    if len(keep_words) > 0:
        title = " ".join(keep_words)
        if title.split(" ")[-1] != "spp.":
            title = title.rstrip(" .:")
    return title

Response: when a title is required generate one from the value


Instruction:
Make a summary of the following Python 3 code
def escape_unmatched_angle_brackets(string, allowed_tag_fragments=()):
    if not string:
        return string

    # Split string on tags
    tags = re.split('(<.*?>)', string)
    #print tags

    for i, val in enumerate(tags):
        # Use angle bracket character counts to find unmatched tags
        #  as well as our allowed_tags list to ignore good tags

        if val.count('<') == val.count('>') and not val.startswith(allowed_tag_fragments):
            val = val.replace('<', '<')
            val = val.replace('>', '>')
        else:
            # Count how many unmatched tags we have
            while val.count('<') != val.count('>'):
                if val.count('<') != val.count('>') and val.count('<') > 0:
                    val = val.replace('<', '<', 1)
                elif val.count('<') != val.count('>') and val.count('>') > 0:
                    val = val.replace('>', '>', 1)
            if val.count('<') == val.count('>') and not val.startswith(allowed_tag_fragments):
                # Send it through again in case there are nested unmatched tags
                val = escape_unmatched_angle_brackets(val, allowed_tag_fragments)

        tags[i] = val

    return ''.join(tags)

Response: This function is used to escape unmatched angle brackets in an XML string.


Instruction:
Can you generate the documentation for the following Python 3 function
def escape_ampersand(string):
    if not string:
        return string
    start_with_match = r"(\#x(....);|lt;|gt;|amp;)"
    # The pattern below is match & that is not immediately followed by #
    string = re.sub(r"&(?!" + start_with_match + ")", '&', string)
    return string

Response: Quick convert unicode ampersand characters not associated with a numbered entity to a plain &amp ;


Instruction:
Here you have a function in Python 3, explain what it does
def parse(filename, return_doctype_dict=False):
    doctype_dict = {}
    # check for python version, doctype in ElementTree is deprecated 3.2 and above
    if sys.version_info < (3,2):
        parser = CustomXMLParser(html=0, target=None, encoding='utf-8')
    else:
        # Assume greater than Python 3.2, get the doctype from the TreeBuilder
        tree_builder = CustomTreeBuilder()
        parser = ElementTree.XMLParser(html=0, target=tree_builder, encoding='utf-8')

    tree = ElementTree.parse(filename, parser)
    root = tree.getroot()

    if sys.version_info < (3,2):
        doctype_dict = parser.doctype_dict
    else:
        doctype_dict = tree_builder.doctype_dict

    if return_doctype_dict is True:
        return root, doctype_dict
    else:
        return root

Response: Parse the file and return the root and doctype dict


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_first_element_index(root, tag_name):
    tag_index = 1
    for tag in root:
        if tag.tag == tag_name:
            # Return the first one found if there is a match
            return tag_index
        tag_index = tag_index + 1
    # Default
    return None

Response: This function returns the index of the first child tag with tag_name in the tree root.


Instruction:
Can you tell what is the following Python 3 function doing
def rewrite_subject_group(root, subjects, subject_group_type, overwrite=True):
    "add or rewrite subject tags inside subj-group tags"
    parent_tag_name = 'subj-group'
    tag_name = 'subject'
    wrap_tag_name = 'article-categories'
    tag_attribute = 'subj-group-type'
    # the parent tag where it should be found
    xpath_parent = './/front/article-meta/article-categories'
    # the wraping tag in case article-categories does not exist
    xpath_article_meta = './/front/article-meta'
    # the xpath to find the subject tags we are interested in
    xpath = './/{parent_tag_name}[@{tag_attribute}="{group_type}"]'.format(
        parent_tag_name=parent_tag_name,
        tag_attribute=tag_attribute,
        group_type=subject_group_type)

    count = 0
    # get the parent tag
    parent_tag = root.find(xpath_parent)
    if parent_tag is None:
        # parent tag not found, add one
        wrap_tag = root.find(xpath_article_meta)
        article_categories_tag = SubElement(wrap_tag, wrap_tag_name)
        parent_tag = article_categories_tag
    insert_index = 0
    # iterate all tags to find the index of the first tag we are interested in
    if parent_tag is not None:
        for tag_index, tag in enumerate(parent_tag.findall('*')):
            if tag.tag == parent_tag_name and tag.get(tag_attribute) == subject_group_type:
                insert_index = tag_index
                if overwrite is True:
                    # if overwriting use the first one found
                    break
            # if not overwriting, use the last one found + 1
            if overwrite is not True:
                insert_index += 1
    # remove the tag if overwriting the existing values
    if overwrite is True:
        # remove all the tags
        for tag in root.findall(xpath):
            parent_tag.remove(tag)
    # add the subjects
    for subject in subjects:
        subj_group_tag = Element(parent_tag_name)
        subj_group_tag.set(tag_attribute, subject_group_type)
        subject_tag = SubElement(subj_group_tag, tag_name)
        subject_tag.text = subject
        parent_tag.insert(insert_index, subj_group_tag)
        count += 1
        insert_index += 1
    return count

Response: add or rewrite subject tags inside subj - group tags


Instruction:
How would you code a function in Python 3 to
build a doctype object.

Response:
def build_doctype(qualifiedName, publicId=None, systemId=None, internalSubset=None):
    """
    Instantiate an ElifeDocumentType, a subclass of minidom.DocumentType, with
    some properties so it is more testable
    """
    doctype = ElifeDocumentType(qualifiedName)
    doctype._identified_mixin_init(publicId, systemId)
    if internalSubset:
        doctype.internalSubset = internalSubset
    return doctype