Instruction:
Create a Python 3 function for
creating |oauth2| request elements.

Response:
def create_request_elements(
            cls, request_type, credentials, url, method='GET', params=None,
            headers=None, body='', secret=None, redirect_uri='', scope='',
            csrf='', user_state=''
    ):
        """
        Creates |oauth2| request elements.
        """

        headers = headers or {}
        params = params or {}

        consumer_key = credentials.consumer_key or ''
        consumer_secret = credentials.consumer_secret or ''
        token = credentials.token or ''
        refresh_token = credentials.refresh_token or credentials.token or ''

        # Separate url base and query parameters.
        url, base_params = cls._split_url(url)

        # Add params extracted from URL.
        params.update(dict(base_params))

        if request_type == cls.USER_AUTHORIZATION_REQUEST_TYPE:
            # User authorization request.
            # TODO: Raise error for specific message for each missing argument.
            if consumer_key and redirect_uri and (
                    csrf or not cls.supports_csrf_protection):
                params['client_id'] = consumer_key
                params['redirect_uri'] = redirect_uri
                params['scope'] = scope
                if cls.supports_user_state:
                    params['state'] = base64.urlsafe_b64encode(
                        json.dumps(
                            {"csrf": csrf, "user_state": user_state}
                        ).encode('utf-8')
                    )
                else:
                    params['state'] = csrf
                params['response_type'] = 'code'

                # Add authorization header
                headers.update(cls._authorization_header(credentials))
            else:
                raise OAuth2Error(
                    'Credentials with valid consumer_key and arguments '
                    'redirect_uri, scope and state are required to create '
                    'OAuth 2.0 user authorization request elements!')

        elif request_type == cls.ACCESS_TOKEN_REQUEST_TYPE:
            # Access token request.
            if consumer_key and consumer_secret:
                params['code'] = token
                params['client_id'] = consumer_key
                params['client_secret'] = consumer_secret
                params['redirect_uri'] = redirect_uri
                params['grant_type'] = 'authorization_code'

                # TODO: Check whether all providers accept it
                headers.update(cls._authorization_header(credentials))
            else:
                raise OAuth2Error(
                    'Credentials with valid token, consumer_key, '
                    'consumer_secret and argument redirect_uri are required '
                    'to create OAuth 2.0 access token request elements!')

        elif request_type == cls.REFRESH_TOKEN_REQUEST_TYPE:
            # Refresh access token request.
            if refresh_token and consumer_key and consumer_secret:
                params['refresh_token'] = refresh_token
                params['client_id'] = consumer_key
                params['client_secret'] = consumer_secret
                params['grant_type'] = 'refresh_token'
            else:
                raise OAuth2Error(
                    'Credentials with valid refresh_token, consumer_key, '
                    'consumer_secret are required to create OAuth 2.0 '
                    'refresh token request elements!')

        elif request_type == cls.PROTECTED_RESOURCE_REQUEST_TYPE:
            # Protected resource request.

            # Add Authorization header. See:
            # http://tools.ietf.org/html/rfc6749#section-7.1
            if credentials.token_type == cls.BEARER:
                # http://tools.ietf.org/html/rfc6750#section-2.1
                headers.update(
                    {'Authorization': 'Bearer {0}'.format(credentials.token)})

            elif token:
                params['access_token'] = token
            else:
                raise OAuth2Error(
                    'Credentials with valid token are required to create '
                    'OAuth 2.0 protected resources request elements!')

        request_elements = core.RequestElements(
            url, method, params, headers, body)

        return cls._x_request_elements_filter(
            request_type, request_elements, credentials)


Instruction:
Implement a Python 3 function for
decoding state and return param.

Response:
def decode_state(cls, state, param='user_state'):
        """
        Decode state and return param.

        :param str state:
            state parameter passed through by provider

        :param str param:
            key to query from decoded state variable. Options include 'csrf'
            and 'user_state'.

        :returns:
            string value from decoded state

        """
        if state and cls.supports_user_state:
            # urlsafe_b64 may include = which the browser quotes so must
            # unquote Cast to str to void b64decode translation error. Base64
            # should be str compatible.
            return json.loads(base64.urlsafe_b64decode(
                unquote(str(state))).decode('utf-8'))[param]
        else:
            return state if param == 'csrf' else ''


Instruction:
How would you code a function in Python 3 to
refresh the credentials for the current user.

Response:
def refresh_credentials(self, credentials):
        """
        Refreshes :class:`.Credentials` if it gives sense.

        :param credentials:
            :class:`.Credentials` to be refreshed.

        :returns:
            :class:`.Response`.

        """

        if not self._x_refresh_credentials_if(credentials):
            return

        # We need consumer key and secret to make this kind of request.
        cfg = credentials.config.get(credentials.provider_name)
        credentials.consumer_key = cfg.get('consumer_key')
        credentials.consumer_secret = cfg.get('consumer_secret')

        request_elements = self.create_request_elements(
            request_type=self.REFRESH_TOKEN_REQUEST_TYPE,
            credentials=credentials,
            url=self.access_token_url,
            method='POST'
        )

        self._log(logging.INFO, u'Refreshing credentials.')
        response = self._fetch(*request_elements)

        # We no longer need consumer info.
        credentials.consumer_key = None
        credentials.consumer_secret = None

        # Extract the refreshed data.
        access_token = response.data.get('access_token')
        refresh_token = response.data.get('refresh_token')

        # Update credentials only if there is access token.
        if access_token:
            credentials.token = access_token
            credentials.expire_in = response.data.get('expires_in')

            # Update refresh token only if there is a new one.
            if refresh_token:
                credentials.refresh_token = refresh_token

            # Handle different naming conventions across providers.
            credentials = self._x_credentials_parser(
                credentials, response.data)

        return response


Instruction:
Implement a Python 3 function for
parsing the credentials from the data.

Response:
def _x_credentials_parser(credentials, data):
        """
        We need to override this method to fix Facebooks naming deviation.
        """

        # Facebook returns "expires" instead of "expires_in".
        credentials.expire_in = data.get('expires')

        if data.get('token_type') == 'bearer':
            # TODO: cls is not available here, hardcode for now.
            credentials.token_type = 'Bearer'

        return credentials


Instruction:
Create a Python 3 function to
filter out the request elements that are not needed by Google.

Response:
def _x_request_elements_filter(cls, request_type, request_elements,
                                   credentials):
        """
        Google doesn't accept client ID and secret to be at the same time in
        request parameters and in the basic authorization header in the access
        token request.
        """
        if request_type is cls.ACCESS_TOKEN_REQUEST_TYPE:
            params = request_elements[2]
            del params['client_id']
            del params['client_secret']
        return request_elements


Instruction:
Create a Python 3 function for
logging-in handler for the user.

Response:
def login(provider_name):
    """
    Login handler, must accept both GET and POST to be able to use OpenID.
    """

    # We need response object for the WerkzeugAdapter.
    response = make_response()

    # Log the user in, pass it the adapter and the provider name.
    result = authomatic.login(
        WerkzeugAdapter(
            request,
            response),
        provider_name)

    # If there is no LoginResult object, the login procedure is still pending.
    if result:
        if result.user:
            # We need to update the user to get more info.
            result.user.update()

        # The rest happens inside the template.
        return render_template('login.html', result=result)

    # Don't forget to return the response.
    return response


Instruction:
Create a Python 3 function for
normalizing a dictionary of items that are single - item iterables with the value of its index 0.

Response:
def normalize_dict(dict_):
    """
    Replaces all values that are single-item iterables with the value of its
    index 0.

    :param dict dict_:
        Dictionary to normalize.

    :returns:
        Normalized dictionary.

    """

    return dict([(k, v[0] if not isinstance(v, str) and len(v) == 1 else v)
                 for k, v in list(dict_.items())])


Instruction:
Can you write a function in Python 3 where it
converts list of tuples to dictionary with duplicate keys converted to lists.

Response:
def items_to_dict(items):
    """
    Converts list of tuples to dictionary with duplicate keys converted to
    lists.

    :param list items:
        List of tuples.

    :returns:
        :class:`dict`

    """

    res = collections.defaultdict(list)

    for k, v in items:
        res[k].append(v)

    return normalize_dict(dict(res))


Instruction:
Here you have a function in Python 3, explain what it does
def json_qs_parser(body):
    try:
        # Try JSON first.
        return json.loads(body)
    except (OverflowError, TypeError, ValueError):
        pass

    try:
        # Then XML.
        return ElementTree.fromstring(body)
    except (ElementTree.ParseError, TypeError, ValueError):
        pass

    # Finally query string.
    return dict(parse.parse_qsl(body))

Response: Parses response body from JSON XML or query string.


Instruction:
How would you code a function in Python 3 to
resolve a provider class by name.

Response:
def resolve_provider_class(class_):
    """
    Returns a provider class.

    :param class_name: :class:`string` or
    :class:`authomatic.providers.BaseProvider` subclass.

    """

    if isinstance(class_, str):
        # prepare path for authomatic.providers package
        path = '.'.join([__package__, 'providers', class_])

        # try to import class by string from providers module or by fully
        # qualified path
        return import_string(class_, True) or import_string(path)
    else:
        return class_


Instruction:
Can you tell what is the following Python 3 function doing
def id_to_name(config, short_name):

    for k, v in list(config.items()):
        if v.get('id') == short_name:
            return k

    raise Exception(
        'No provider with id={0} found in the config!'.format(short_name))

Response: Returns the provider key based on it s id value.


Instruction:
Can you tell what is the following Python 3 function doing
def create_cookie(self, delete=None):
        value = 'deleted' if delete else self._serialize(self.data)
        split_url = parse.urlsplit(self.adapter.url)
        domain = split_url.netloc.split(':')[0]

        # Work-around for issue #11, failure of WebKit-based browsers to accept
        # cookies set as part of a redirect response in some circumstances.
        if '.' not in domain:
            template = '{name}={value}; Path={path}; HttpOnly{secure}{expires}'
        else:
            template = ('{name}={value}; Domain={domain}; Path={path}; '
                        'HttpOnly{secure}{expires}')

        return template.format(
            name=self.name,
            value=value,
            domain=domain,
            path=split_url.path,
            secure='; Secure' if self.secure else '',
            expires='; Expires=Thu, 01-Jan-1970 00:00:01 GMT' if delete else ''
        )

Response: Creates the value for Set - Cookie HTTP header.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def save(self):
        if self.data:
            cookie = self.create_cookie()
            cookie_len = len(cookie)

            if cookie_len > 4093:
                raise SessionError('Cookie too long! The cookie size {0} '
                                   'is more than 4093 bytes.'
                                   .format(cookie_len))

            self.adapter.set_header('Set-Cookie', cookie)

            # Reset data
            self._data = {}

Response: Saves the current state of the object to the adapter.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _get_data(self):
        cookie = self.adapter.cookies.get(self.name)
        return self._deserialize(cookie) if cookie else {}

Response: Extracts the session data from the cookie.


Instruction:
Create a Python 3 function for
getting the session data lazily.

Response:
def data(self):
        """
        Gets session data lazily.
        """
        if not self._data:
            self._data = self._get_data()
        # Always return a dict, even if deserialization returned nothing
        if self._data is None:
            self._data = {}
        return self._data


Instruction:
Write a Python 3 function for
creating a signature for the session.

Response:
def _signature(self, *parts):
        """
        Creates signature for the session.
        """
        signature = hmac.new(six.b(self.secret), digestmod=hashlib.sha1)
        signature.update(six.b('|'.join(parts)))
        return signature.hexdigest()


Instruction:
Can you generate the documentation for the following Python 3 function
def _serialize(self, value):

        # data = copy.deepcopy(value)
        data = value

        # 1. Serialize
        serialized = pickle.dumps(data).decode('latin-1')

        # 2. Encode
        # Percent encoding produces smaller result then urlsafe base64.
        encoded = parse.quote(serialized, '')

        # 3. Concatenate
        timestamp = str(int(time.time()))
        signature = self._signature(self.name, encoded, timestamp)
        concatenated = '|'.join([encoded, timestamp, signature])

        return concatenated

Response: Converts the value to a signed string with timestamp.


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

        # 3. Split
        encoded, timestamp, signature = value.split('|')

        # Verify signature
        if not signature == self._signature(self.name, encoded, timestamp):
            raise SessionError('Invalid signature "{0}"!'.format(signature))

        # Verify timestamp
        if int(timestamp) < int(time.time()) - self.max_age:
            return None

        # 2. Decode
        decoded = parse.unquote(encoded)

        # 1. Deserialize
        deserialized = pickle.loads(decoded.encode('latin-1'))

        return deserialized

Response: Deserializes and verifies the value created by _serialize.


Instruction:
Write a Python 3 script to
convert the user instance to a dict.

Response:
def to_dict(self):
        """
        Converts the :class:`.User` instance to a :class:`dict`.

        :returns:
            :class:`dict`

        """

        # copy the dictionary
        d = copy.copy(self.__dict__)

        # Keep only the provider name to avoid circular reference
        d['provider'] = self.provider.name
        d['credentials'] = self.credentials.serialize(
        ) if self.credentials else None
        d['birth_date'] = str(d['birth_date'])

        # Remove content
        d.pop('content')

        if isinstance(self.data, ElementTree.Element):
            d['data'] = None

        return d


Instruction:
Can you write a function in Python 3 where it
sets the expiration time of the resource.

Response:
def expire_in(self, value):
        """
        Computes :attr:`.expiration_time` when the value is set.
        """

        # pylint:disable=attribute-defined-outside-init
        if value:
            self._expiration_time = int(time.time()) + int(value)
            self._expire_in = value


Instruction:
Explain what the following Python 3 code does
def valid(self):

        if self.expiration_time:
            return self.expiration_time > int(time.time())
        else:
            return True

Response: Returns True if credentials are valid False otherwise.


Instruction:
Create a Python 3 function to
return True if the credentials expire sooner than specified number of seconds.

Response:
def expire_soon(self, seconds):
        """
        Returns ``True`` if credentials expire sooner than specified.

        :param int seconds:
            Number of seconds.

        :returns:
            ``True`` if credentials expire sooner than specified,
            else ``False``.

        """

        if self.expiration_time:
            return self.expiration_time < int(time.time()) + int(seconds)
        else:
            return False


Instruction:
Given the following Python 3 function, write the documentation
def refresh(self, force=False, soon=86400):

        if hasattr(self.provider_class, 'refresh_credentials'):
            if force or self.expire_soon(soon):
                logging.info('PROVIDER NAME: {0}'.format(self.provider_name))
                return self.provider_class(
                    self, None, self.provider_name).refresh_credentials(self)

Response: Refreshes the credentials of the user in the cache.


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

        if self.provider_id is None:
            raise ConfigError(
                'To serialize credentials you need to specify a '
                'unique integer under the "id" key in the config '
                'for each provider!')

        # Get the provider type specific items.
        rest = self.provider_type_class().to_tuple(self)

        # Provider ID and provider type ID are always the first two items.
        result = (self.provider_id, self.provider_type_id) + rest

        # Make sure that all items are strings.
        stringified = [str(i) for i in result]

        # Concatenate by newline.
        concatenated = '\n'.join(stringified)

        # Percent encode.
        return parse.quote(concatenated, '')

Response: Converts the credentials to a percent encoded string to be stored for later use.


Instruction:
Make a summary of the following Python 3 code
def popup_js(self, callback_name=None, indent=None,
                 custom=None, stay_open=False):
        """
        Returns JavaScript that:

        #.  Triggers the ``options.onLoginComplete(result, closer)``
            handler set with the :ref:`authomatic.setup() <js_setup>`
            function of :ref:`javascript.js <js>`.
        #.  Calls the JavasScript callback specified by :data:`callback_name`
            on the opener of the *login handler popup* and passes it the
            *login result* JSON object as first argument and the `closer`
            function which you should call in your callback to close the popup.

        :param str callback_name:
            The name of the javascript callback e.g ``foo.bar.loginCallback``
            will result in ``window.opener.foo.bar.loginCallback(result);``
            in the HTML.

        :param int indent:
            The number of spaces to indent the JSON result object.
            If ``0`` or negative, only newlines are added.
            If ``None``, no newlines are added.

        :param custom:
            Any JSON serializable object that will be passed to the
            ``result.custom`` attribute.

        :param str stay_open:
            If ``True``, the popup will stay open.

        :returns:
            :class:`str` with JavaScript.

        """

        custom_callback = """
        try {{ window.opener.{cb}(result, closer); }} catch(e) {{}}
        """.format(cb=callback_name) if callback_name else ''

        # TODO: Move the window.close() to the opener
        return """
        (function(){{

            closer = function(){{
                window.close();
            }};

            var result = {result};
            result.custom = {custom};

            {custom_callback}

            try {{
                window.opener.authomatic.loginComplete(result, closer);
            }} catch(e) {{}}

        }})();

        """.format(result=self.to_json(indent),
                   custom=json.dumps(custom),
                   custom_callback=custom_callback,
                   stay_open='// ' if stay_open else '')

Response: Returns JavaScript that will display the user in the popup.


Instruction:
Can you generate the documentation for the following Python 3 function
def popup_html(self, callback_name=None, indent=None,
                   title='Login | {0}', custom=None, stay_open=False):
        """
        Returns a HTML with JavaScript that:

        #.  Triggers the ``options.onLoginComplete(result, closer)`` handler
            set with the :ref:`authomatic.setup() <js_setup>` function of
            :ref:`javascript.js <js>`.
        #.  Calls the JavasScript callback specified by :data:`callback_name`
            on the opener of the *login handler popup* and passes it the
            *login result* JSON object as first argument and the `closer`
            function which you should call in your callback to close the popup.

        :param str callback_name:
            The name of the javascript callback e.g ``foo.bar.loginCallback``
            will result in ``window.opener.foo.bar.loginCallback(result);``
            in the HTML.

        :param int indent:
            The number of spaces to indent the JSON result object.
            If ``0`` or negative, only newlines are added.
            If ``None``, no newlines are added.

        :param str title:
            The text of the HTML title. You can use ``{0}`` tag inside,
            which will be replaced by the provider name.

        :param custom:
            Any JSON serializable object that will be passed to the
            ``result.custom`` attribute.

        :param str stay_open:
            If ``True``, the popup will stay open.

        :returns:
            :class:`str` with HTML.

        """

        return """
        <!DOCTYPE html>
        <html>
            <head><title>{title}</title></head>
            <body>
            <script type="text/javascript">
                {js}
            </script>
            </body>
        </html>
        """.format(
            title=title.format(self.provider.name if self.provider else ''),
            js=self.popup_js(callback_name, indent, custom, stay_open)
        )

Response: Returns a JavasScript popup HTML with JavaScript that will be used to display the login result in the browser.


Instruction:
Make a summary of the following Python 3 code
def is_binary_string(content):

        textchars = (bytearray([7, 8, 9, 10, 12, 13, 27]) +
                     bytearray(range(0x20, 0x100)))
        return bool(content.translate(None, textchars))

Response: Return true if string is binary data.


Instruction:
Create a Python 3 function for
returning the content of the response.

Response:
def content(self):
        """
        The whole response content.
        """

        if not self._content:
            content = self.httplib_response.read()
            if self.is_binary_string(content):
                self._content = content
            else:
                self._content = content.decode('utf-8')
        return self._content


Instruction:
Can you tell what is the following Python 3 function doing
def data(self):

        if not self._data:
            self._data = self.content_parser(self.content)
        return self._data

Response: A dict of data parsed from content.


Instruction:
Implement a function in Python 3 to
login to the specified provider.

Response:
def login(self, adapter, provider_name, callback=None,
              session=None, session_saver=None, **kwargs):
        """
        If :data:`provider_name` specified, launches the login procedure for
        corresponding :doc:`provider </reference/providers>` and returns
        :class:`.LoginResult`.

        If :data:`provider_name` is empty, acts like
        :meth:`.Authomatic.backend`.

        .. warning::

            The method redirects the **user** to the **provider** which in
            turn redirects **him/her** back to the *request handler* where
            it has been called.

        :param str provider_name:
            Name of the provider as specified in the keys of the :doc:`config`.

        :param callable callback:
            If specified the method will call the callback with
            :class:`.LoginResult` passed as argument and will return nothing.

        :param bool report_errors:

        .. note::

            Accepts additional keyword arguments that will be passed to
            :doc:`provider <providers>` constructor.

        :returns:
            :class:`.LoginResult`

        """

        if provider_name:
            # retrieve required settings for current provider and raise
            # exceptions if missing
            provider_settings = self.config.get(provider_name)
            if not provider_settings:
                raise ConfigError('Provider name "{0}" not specified!'
                                  .format(provider_name))

            if not (session is None or session_saver is None):
                session = session
                session_saver = session_saver
            else:
                session = Session(adapter=adapter,
                                  secret=self.secret,
                                  max_age=self.session_max_age,
                                  name=self.prefix,
                                  secure=self.secure_cookie)

                session_saver = session.save

            # Resolve provider class.
            class_ = provider_settings.get('class_')
            if not class_:
                raise ConfigError(
                    'The "class_" key not specified in the config'
                    ' for provider {0}!'.format(provider_name))
            ProviderClass = resolve_provider_class(class_)

            # FIXME: Find a nicer solution
            ProviderClass._logger = self._logger

            # instantiate provider class
            provider = ProviderClass(self,
                                     adapter=adapter,
                                     provider_name=provider_name,
                                     callback=callback,
                                     session=session,
                                     session_saver=session_saver,
                                     **kwargs)

            # return login result
            return provider.login()

        else:
            # Act like backend.
            self.backend(adapter)


Instruction:
How would you implement a function in Python 3 that
accesses protected resource on behalf of the user.

Response:
def access(self, credentials, url, params=None, method='GET',
               headers=None, body='', max_redirects=5, content_parser=None):
        """
        Accesses **protected resource** on behalf of the **user**.

        :param credentials:
            The **user's** :class:`.Credentials` (serialized or normal).

        :param str url:
            The **protected resource** URL.

        :param str method:
            HTTP method of the request.

        :param dict headers:
            HTTP headers of the request.

        :param str body:
            Body of ``POST``, ``PUT`` and ``PATCH`` requests.

        :param int max_redirects:
            Maximum number of HTTP redirects to follow.

        :param function content_parser:
            A function to be used to parse the :attr:`.Response.data`
            from :attr:`.Response.content`.

        :returns:
            :class:`.Response`

        """

        # Deserialize credentials.
        credentials = Credentials.deserialize(self.config, credentials)

        # Resolve provider class.
        ProviderClass = credentials.provider_class
        logging.info('ACCESS HEADERS: {0}'.format(headers))
        # Access resource and return response.

        provider = ProviderClass(
            self, adapter=None, provider_name=credentials.provider_name)
        provider.credentials = credentials

        return provider.access(url=url,
                               params=params,
                               method=method,
                               headers=headers,
                               body=body,
                               max_redirects=max_redirects,
                               content_parser=content_parser)


Instruction:
Here you have a function in Python 3, explain what it does
def request_elements(
            self, credentials=None, url=None, method='GET', params=None,
            headers=None, body='', json_input=None, return_json=False
    ):
        """
        Creates request elements for accessing **protected resource of a
        user**. Required arguments are :data:`credentials` and :data:`url`. You
        can pass :data:`credentials`, :data:`url`, :data:`method`, and
        :data:`params` as a JSON object.

        :param credentials:
            The **user's** credentials (can be serialized).

        :param str url:
            The url of the protected resource.

        :param str method:
            The HTTP method of the request.

        :param dict params:
            Dictionary of request parameters.

        :param dict headers:
            Dictionary of request headers.

        :param str body:
            Body of ``POST``, ``PUT`` and ``PATCH`` requests.

        :param str json_input:
            you can pass :data:`credentials`, :data:`url`, :data:`method`,
            :data:`params` and :data:`headers` in a JSON object.
            Values from arguments will be used for missing properties.

            ::

                {
                    "credentials": "###",
                    "url": "https://example.com/api",
                    "method": "POST",
                    "params": {
                        "foo": "bar"
                    },
                    "headers": {
                        "baz": "bing",
                        "Authorization": "Bearer ###"
                    },
                    "body": "Foo bar baz bing."
                }

        :param bool return_json:
            if ``True`` the function returns a json object.

            ::

                {
                    "url": "https://example.com/api",
                    "method": "POST",
                    "params": {
                        "access_token": "###",
                        "foo": "bar"
                    },
                    "headers": {
                        "baz": "bing",
                        "Authorization": "Bearer ###"
                    },
                    "body": "Foo bar baz bing."
                }

        :returns:
            :class:`.RequestElements` or JSON string.

        """

        # Parse values from JSON
        if json_input:
            parsed_input = json.loads(json_input)

            credentials = parsed_input.get('credentials', credentials)
            url = parsed_input.get('url', url)
            method = parsed_input.get('method', method)
            params = parsed_input.get('params', params)
            headers = parsed_input.get('headers', headers)
            body = parsed_input.get('body', body)

        if not credentials and url:
            raise RequestElementsError(
                'To create request elements, you must provide credentials '
                'and URL either as keyword arguments or in the JSON object!')

        # Get the provider class
        credentials = Credentials.deserialize(self.config, credentials)
        ProviderClass = credentials.provider_class

        # Create request elements
        request_elements = ProviderClass.create_request_elements(
            ProviderClass.PROTECTED_RESOURCE_REQUEST_TYPE,
            credentials=credentials,
            url=url,
            method=method,
            params=params,
            headers=headers,
            body=body)

        if return_json:
            return request_elements.to_json()

        else:
            return request_elements

Response: Creates a request element for accessing a protected resource of a user.


Instruction:
Can you tell what is the following Python 3 function doing
def backend(self, adapter):

        AUTHOMATIC_HEADER = 'Authomatic-Response-To'

        # Collect request params
        request_type = adapter.params.get('type', 'auto')
        json_input = adapter.params.get('json')
        credentials = adapter.params.get('credentials')
        url = adapter.params.get('url')
        method = adapter.params.get('method', 'GET')
        body = adapter.params.get('body', '')

        params = adapter.params.get('params')
        params = json.loads(params) if params else {}

        headers = adapter.params.get('headers')
        headers = json.loads(headers) if headers else {}

        ProviderClass = Credentials.deserialize(
            self.config, credentials).provider_class

        if request_type == 'auto':
            # If there is a "callback" param, it's a JSONP request.
            jsonp = params.get('callback')

            # JSONP is possible only with GET method.
            if ProviderClass.supports_jsonp and method is 'GET':
                request_type = 'elements'
            else:
                # Remove the JSONP callback
                if jsonp:
                    params.pop('callback')
                request_type = 'fetch'

        if request_type == 'fetch':
            # Access protected resource
            response = self.access(
                credentials, url, params, method, headers, body)
            result = response.content

            # Forward status
            adapter.status = str(response.status) + ' ' + str(response.reason)

            # Forward headers
            for k, v in response.getheaders():
                logging.info('    {0}: {1}'.format(k, v))
                adapter.set_header(k, v)

        elif request_type == 'elements':
            # Create request elements
            if json_input:
                result = self.request_elements(
                    json_input=json_input, return_json=True)
            else:
                result = self.request_elements(credentials=credentials,
                                               url=url,
                                               method=method,
                                               params=params,
                                               headers=headers,
                                               body=body,
                                               return_json=True)

            adapter.set_header('Content-Type', 'application/json')
        else:
            result = '{"error": "Bad Request!"}'

        # Add the authomatic header
        adapter.set_header(AUTHOMATIC_HEADER, request_type)

        # Write result to response
        adapter.write(result)

Response: Converts a webapp2. RequestHandler to a JSON backend which can use with a specific HTTP method.


Instruction:
Can you tell what is the following Python 3 function doing
def _normalize_params(params):

    if isinstance(params, dict):
        params = list(params.items())

    # remove "realm" and "oauth_signature"
    params = sorted([
        (k, v) for k, v in params
        if k not in ('oauth_signature', 'realm')
    ])
    # sort
    # convert to query string
    qs = parse.urlencode(params)
    # replace "+" to "%20"
    qs = qs.replace('+', '%20')
    # replace "%7E" to "%20"
    qs = qs.replace('%7E', '~')

    return qs

Response: Normalizes the parameters of the current request.


Instruction:
Write a Python 3 script to
create base string for HMAC - SHA1 signature as specified in RFC 5246 section 9. 1. 3.

Response:
def _create_base_string(method, base, params):
    """
    Returns base string for HMAC-SHA1 signature as specified in:
    http://oauth.net/core/1.0a/#rfc.section.9.1.3.
    """

    normalized_qs = _normalize_params(params)
    return _join_by_ampersand(method, base, normalized_qs)


Instruction:
Can you tell what is the following Python 3 function doing
def create_signature(cls, method, base, params,
                         consumer_secret, token_secret=''):
        """
        Returns HMAC-SHA1 signature as specified at:
        http://oauth.net/core/1.0a/#rfc.section.9.2.

        :param str method:
            HTTP method of the request to be signed.

        :param str base:
            Base URL of the request without query string an fragment.

        :param dict params:
            Dictionary or list of tuples of the request parameters.

        :param str consumer_secret:
            :attr:`.core.Consumer.secret`

        :param str token_secret:
            Access token secret as specified in
            http://oauth.net/core/1.0a/#anchor3.

        :returns:
            The signature string.

        """

        base_string = _create_base_string(method, base, params)
        key = cls._create_key(consumer_secret, token_secret)

        hashed = hmac.new(
            six.b(key),
            base_string.encode('utf-8'),
            hashlib.sha1)

        base64_encoded = binascii.b2a_base64(hashed.digest())[:-1]

        return base64_encoded

Response: Creates a base64 - encoded HMAC - SHA1 signature for the request.


Instruction:
Make a summary of the following Python 3 code
def create_request_elements(
            cls, request_type, credentials, url, params=None, headers=None,
            body='', method='GET', verifier='', callback=''
    ):
        """
        Creates |oauth1| request elements.
        """

        params = params or {}
        headers = headers or {}

        consumer_key = credentials.consumer_key or ''
        consumer_secret = credentials.consumer_secret or ''
        token = credentials.token or ''
        token_secret = credentials.token_secret or ''

        # separate url base and query parameters
        url, base_params = cls._split_url(url)

        # add extracted params to future params
        params.update(dict(base_params))

        if request_type == cls.USER_AUTHORIZATION_REQUEST_TYPE:
            # no need for signature
            if token:
                params['oauth_token'] = token
            else:
                raise OAuth1Error(
                    'Credentials with valid token are required to create '
                    'User Authorization URL!')
        else:
            # signature needed
            if request_type == cls.REQUEST_TOKEN_REQUEST_TYPE:
                # Request Token URL
                if consumer_key and consumer_secret and callback:
                    params['oauth_consumer_key'] = consumer_key
                    params['oauth_callback'] = callback
                else:
                    raise OAuth1Error(
                        'Credentials with valid consumer_key, consumer_secret '
                        'and callback are required to create Request Token '
                        'URL!')

            elif request_type == cls.ACCESS_TOKEN_REQUEST_TYPE:
                # Access Token URL
                if consumer_key and consumer_secret and token and verifier:
                    params['oauth_token'] = token
                    params['oauth_consumer_key'] = consumer_key
                    params['oauth_verifier'] = verifier
                else:
                    raise OAuth1Error(
                        'Credentials with valid consumer_key, '
                        'consumer_secret, token and argument verifier'
                        ' are required to create Access Token URL!')

            elif request_type == cls.PROTECTED_RESOURCE_REQUEST_TYPE:
                # Protected Resources URL
                if consumer_key and consumer_secret and token and token_secret:
                    params['oauth_token'] = token
                    params['oauth_consumer_key'] = consumer_key
                else:
                    raise OAuth1Error(
                        'Credentials with valid consumer_key, ' +
                        'consumer_secret, token and token_secret are required '
                        'to create Protected Resources URL!')

            # Sign request.
            # http://oauth.net/core/1.0a/#anchor13

            # Prepare parameters for signature base string
            # http://oauth.net/core/1.0a/#rfc.section.9.1
            params['oauth_signature_method'] = cls._signature_generator.method
            params['oauth_timestamp'] = str(int(time.time()))
            params['oauth_nonce'] = cls.csrf_generator(str(uuid.uuid4()))
            params['oauth_version'] = '1.0'

            # add signature to params
            params['oauth_signature'] = cls._signature_generator.create_signature(  # noqa
                method, url, params, consumer_secret, token_secret)

        request_elements = core.RequestElements(
            url, method, params, headers, body)

        return cls._x_request_elements_filter(
            request_type, request_elements, credentials)

Response: Creates |oauth1| request elements.


Instruction:
How would you explain what the following Python 3 function does
def _access_user_info(self):
        response = super(Bitbucket, self)._access_user_info()

        response.data.setdefault("email", None)

        email_response = self.access(self.user_email_url)
        if email_response.data:
            for item in email_response.data:
                if item.get("primary", False):
                    response.data.update(email=item.get("email", None))

        return response

Response: Get user info from Bitbucket


Instruction:
How would you explain what the following Python 3 function does
def _access_user_info(self):
        response = super(Vimeo, self)._access_user_info()
        uid = response.data.get('oauth', {}).get('user', {}).get('id')
        if uid:
            return self.access('http://vimeo.com/api/v2/{0}/info.json'
                               .format(uid))
        return response

Response: Access the user info endpoint


Instruction:
How would you explain what the following Python 3 function does
def login(self, *login_args, **login_kwargs):

        def decorator(f):
            @wraps(f)
            def decorated(*args, **kwargs):
                self.response = make_response()
                adapter = WerkzeugAdapter(request, self.response)
                login_kwargs.setdefault('session', session)
                login_kwargs.setdefault('session_saver', self.session_saver)
                self.result = super(FlaskAuthomatic, self).login(
                    adapter,
                    *login_args,
                    **login_kwargs)
                return f(*args, **kwargs)
            return decorated
        return decorator

Response: Decorator for Flask view functions.


Instruction:
Here you have a function in Python 3, explain what it does
def get(cls, key, default=None):

        # Query datastore.
        result = cls.query(cls.provider_name == key).get()

        if result:
            result_dict = result.to_dict()

            # Use NDBOpenIDStore by default
            result_dict['store'] = NDBOpenIDStore

            # Convert coma-separated values to list. Currently only scope is
            # csv.
            for i in ('scope', ):
                prop = result_dict.get(i)
                if prop:
                    result_dict[i] = [s.strip() for s in prop.split(',')]
                else:
                    result_dict[i] = None

            return result_dict
        else:
            return default

Response: Returns a configuration dictionary for the specified provider.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def values(cls):

        # get all items
        results = cls.query().fetch()
        # return list of dictionaries
        return [result.to_dict() for result in results]

Response: Returns a list of dictionaries containing all items in the current database.


Instruction:
Can you tell what is the following Python 3 function doing
def initialize(cls):

        if not len(cls.query().fetch()):

            example = cls.get_or_insert('Example')

            example.class_ = 'Provider class e.g. ' + \
                             '"authomatic.providers.oauth2.Facebook".'
            example.provider_name = 'Your custom provider name e.g. "fb".'

            # AuthorizationProvider
            example.consumer_key = 'Consumer key.'
            example.consumer_secret = 'Consumer secret'
            example.provider_id = 1

            # OAuth2
            example.scope = 'coma, separated, list, of, scopes'

            # AuthenticationProvider
            example.identifier_param = 'Querystring parameter for claimed ' + \
                                       'id. default is "id"'

            # Save the example
            example.put()

            # Raise an information error.
            raise GAEError(
                'A NDBConfig data model was created! Go to Datastore Viewer '
                'in your dashboard and populate it with data!')

Response: Initializes the data model for the given NDBConfig class.


Instruction:
Can you generate the documentation for the following Python 3 function
def login(self):

        if self.params.get(self.identifier_param):
            # =================================================================
            # Phase 1 before redirect.
            # =================================================================
            self._log(
                logging.INFO,
                u'Starting OpenID authentication procedure.')

            url = users.create_login_url(
                dest_url=self.url, federated_identity=self.identifier)

            self._log(logging.INFO, u'Redirecting user to {0}.'.format(url))

            self.redirect(url)
        else:
            # =================================================================
            # Phase 2 after redirect.
            # =================================================================

            self._log(
                logging.INFO,
                u'Continuing OpenID authentication procedure after redirect.')

            user = users.get_current_user()

            if user:
                self._log(logging.INFO, u'Authentication successful.')
                self._log(logging.INFO, u'Creating user.')
                self.user = core.User(self,
                                      id=user.federated_identity(),
                                      email=user.email(),
                                      gae_user=user)

                # =============================================================
                # We're done
                # =============================================================
            else:
                raise FailureError(
                    'Unable to authenticate identifier "{0}"!'.format(
                        self.identifier))

Response: Launches the OpenID authentication procedure.


Instruction:
Explain what the following Python 3 code does
def _error_traceback_html(exc_info, traceback_):

    html = """

            <title>ERROR: {error}</title>

The Authomatic library encountered an error!

{error}

{traceback}

    """

    return html.format(error=exc_info[1], traceback=traceback_)

Response: Generates error traceback HTML.


Instruction:
Write a Python 3 script to
decorate the :meth:`.BaseProvider.login` implementations with this decorator. Provides mechanism for error reporting and returning result which makes the :meth:`.BaseProvider.login` implementation cleaner.

Response:
def login_decorator(func):
    """
    Decorate the :meth:`.BaseProvider.login` implementations with this
    decorator.

    Provides mechanism for error reporting and returning result which
    makes the :meth:`.BaseProvider.login` implementation cleaner.

    """

    def wrap(provider, *args, **kwargs):
        error = None
        result = authomatic.core.LoginResult(provider)

        try:
            func(provider, *args, **kwargs)
        except Exception as e:  # pylint:disable=broad-except
            if provider.settings.report_errors:
                error = e
                if not isinstance(error, CancellationError):
                    provider._log(
                        logging.ERROR,
                        u'Reported suppressed exception: {0}!'.format(
                            repr(error)),
                        exc_info=1)
            else:
                if provider.settings.debug:
                    # TODO: Check whether it actually works without middleware
                    provider.write(
                        _error_traceback_html(
                            sys.exc_info(),
                            traceback.format_exc()))
                raise

        # If there is user or error the login procedure has finished
        if provider.user or error:
            result = authomatic.core.LoginResult(provider)
            # Add error to result
            result.error = error

            # delete session cookie
            if isinstance(provider.session, authomatic.core.Session):
                provider.session.delete()

            provider._log(logging.INFO, u'Procedure finished.')

            if provider.callback:
                provider.callback(result)
            return result
        else:
            # Save session
            provider.save_session()

    return wrap


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

        return dict(name=self.name,
                    id=getattr(self, 'id', None),
                    type_id=self.type_id,
                    type=self.get_type(),
                    scope=getattr(self, 'scope', None),
                    user=self.user.id if self.user else None)

Response: Converts the provider instance to a dict.


Instruction:
How would you implement a function in Python 3 that
resolves keyword arguments from constructor or config.

Response:
def _kwarg(self, kwargs, kwname, default=None):
        """
        Resolves keyword arguments from constructor or :doc:`config`.

        .. note::

            The keyword arguments take this order of precedence:

            1. Arguments passed to constructor through the
               :func:`authomatic.login`.
            2. Provider specific arguments from :doc:`config`.
            3. Arguments from :doc:`config` set in the ``__defaults__`` key.
            2. The value from :data:`default` argument.

        :param dict kwargs:
            Keyword arguments dictionary.
        :param str kwname:
            Name of the desired keyword argument.

        """

        return kwargs.get(kwname) or \
            self.settings.config.get(self.name, {}).get(kwname) or \
            self.settings.config.get('__defaults__', {}).get(kwname) or \
            default


Instruction:
Make a summary of the following Python 3 code
def _session_key(self, key):

        return '{0}:{1}:{2}'.format(self.settings.prefix, self.name, key)

Response: Generates session key string.


Instruction:
Implement a function in Python 3 to
set a value to the session.

Response:
def _session_set(self, key, value):
        """
        Saves a value to session.
        """

        self.session[self._session_key(key)] = value


Instruction:
Can you generate the documentation for the following Python 3 function
def csrf_generator(secret):

        # Create hash from random string plus salt.
        hashed = hashlib.md5(uuid.uuid4().bytes + six.b(secret)).hexdigest()

        # Each time return random portion of the hash.
        span = 5
        shift = random.randint(0, span)
        return hashed[shift:shift - span - 1]

Response: Generates a random CSRF token.


Instruction:
Can you create a Python 3 function that
logs a message with pre - formatted prefix.

Response:
def _log(cls, level, msg, **kwargs):
        """
        Logs a message with pre-formatted prefix.

        :param int level:
            Logging level as specified in the
            `login module <http://docs.python.org/2/library/logging.html>`_ of
            Python standard library.

        :param str msg:
            The actual message.

        """

        logger = getattr(cls, '_logger', None) or authomatic.core._logger
        logger.log(
            level, ': '.join(
                ('authomatic', cls.__name__, msg)), **kwargs)


Instruction:
Given the following Python 3 function, write the documentation
def _fetch(self, url, method='GET', params=None, headers=None,
               body='', max_redirects=5, content_parser=None):
        """
        Fetches a URL.

        :param str url:
            The URL to fetch.

        :param str method:
            HTTP method of the request.

        :param dict params:
            Dictionary of request parameters.

        :param dict headers:
            HTTP headers of the request.

        :param str body:
            Body of ``POST``, ``PUT`` and ``PATCH`` requests.

        :param int max_redirects:
            Number of maximum HTTP redirects to follow.

        :param function content_parser:
            A callable to be used to parse the :attr:`.Response.data`
            from :attr:`.Response.content`.

        """
        # 'magic' using _kwarg method
        # pylint:disable=no-member
        params = params or {}
        params.update(self.access_params)

        headers = headers or {}
        headers.update(self.access_headers)

        scheme, host, path, query, fragment = parse.urlsplit(url)
        query = parse.urlencode(params)

        if method in ('POST', 'PUT', 'PATCH'):
            if not body:
                # Put querystring to body
                body = query
                query = ''
                headers.update(
                    {'Content-Type': 'application/x-www-form-urlencoded'})
        request_path = parse.urlunsplit(('', '', path or '', query or '', ''))

        self._log(logging.DEBUG, u' \u251C\u2500 host: {0}'.format(host))
        self._log(
            logging.DEBUG,
            u' \u251C\u2500 path: {0}'.format(request_path))
        self._log(logging.DEBUG, u' \u251C\u2500 method: {0}'.format(method))
        self._log(logging.DEBUG, u' \u251C\u2500 body: {0}'.format(body))
        self._log(logging.DEBUG, u' \u251C\u2500 params: {0}'.format(params))
        self._log(logging.DEBUG, u' \u2514\u2500 headers: {0}'.format(headers))

        # Connect
        if scheme.lower() == 'https':
            connection = http_client.HTTPSConnection(host)
        else:
            connection = http_client.HTTPConnection(host)

        try:
            connection.request(method, request_path, body, headers)
        except Exception as e:
            raise FetchError('Fetching URL failed',
                             original_message=str(e),
                             url=request_path)

        response = connection.getresponse()
        location = response.getheader('Location')

        if response.status in (300, 301, 302, 303, 307) and location:
            if location == url:
                raise FetchError('Url redirects to itself!',
                                 url=location,
                                 status=response.status)

            elif max_redirects > 0:
                remaining_redirects = max_redirects - 1

                self._log(logging.DEBUG, u'Redirecting to {0}'.format(url))
                self._log(logging.DEBUG, u'Remaining redirects: {0}'
                          .format(remaining_redirects))

                # Call this method again.
                response = self._fetch(url=location,
                                       params=params,
                                       method=method,
                                       headers=headers,
                                       max_redirects=remaining_redirects)

            else:
                raise FetchError('Max redirects reached!',
                                 url=location,
                                 status=response.status)
        else:
            self._log(logging.DEBUG, u'Got response:')
            self._log(logging.DEBUG, u' \u251C\u2500 url: {0}'.format(url))
            self._log(
                logging.DEBUG,
                u' \u251C\u2500 status: {0}'.format(
                    response.status))
            self._log(
                logging.DEBUG,
                u' \u2514\u2500 headers: {0}'.format(
                    response.getheaders()))

        return authomatic.core.Response(response, content_parser)

Response:
Fetches a URL.

        :param str url:
            The URL to fetch.

        :param str method:
            HTTP method of the request.

        :param dict params:
            Dictionary of request parameters.

        :param dict headers:
            HTTP headers of the request.

        :param str body:
            Body of ``POST``, ``PUT`` and ``PATCH`` requests.

        :param int max_redirects:
            Number of maximum HTTP redirects to follow.

        :param function content_parser:
            A callable to be used to parse the :attr:`.Response.data`
            from :attr:`.Response.content`.


Instruction:
Implement a Python 3 function for
updating or creates a user object.

Response:
def _update_or_create_user(self, data, credentials=None, content=None):
        """
        Updates or creates :attr:`.user`.

        :returns:
            :class:`.User`

        """

        if not self.user:
            self.user = authomatic.core.User(self, credentials=credentials)

        self.user.content = content
        self.user.data = data

        # Update.
        for key in self.user.__dict__:
            # Exclude data.
            if key not in ('data', 'content'):
                # Extract every data item whose key matches the user
                # property name, but only if it has a value.
                value = data.get(key)
                if value:
                    setattr(self.user, key, value)

        # Handle different structure of data by different providers.
        self.user = self._x_user_parser(self.user, data)

        if self.user.id:
            self.user.id = str(self.user.id)

        # TODO: Move to User
        # If there is no user.name,
        if not self.user.name:
            if self.user.first_name and self.user.last_name:
                # Create it from first name and last name if available.
                self.user.name = ' '.join((self.user.first_name,
                                           self.user.last_name))
            else:
                # Or use one of these.
                self.user.name = (self.user.username or self.user.nickname or
                                  self.user.first_name or self.user.last_name)

        if not self.user.location:
            if self.user.city and self.user.country:
                self.user.location = '{0}, {1}'.format(self.user.city,
                                                       self.user.country)
            else:
                self.user.location = self.user.city or self.user.country

        return self.user


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _http_status_in_category(status, category):

        assert category < 10, 'HTTP status category must be a one-digit int!'
        cat = category * 100
        return status >= cat and status < cat + 100

Response: Checks whether a HTTP status code is in the specified category.


Instruction:
Can you write a function in Python 3 where it
fetches a protected resource from the API.

Response:
def access(self, url, params=None, method='GET', headers=None,
               body='', max_redirects=5, content_parser=None):
        """
        Fetches the **protected resource** of an authenticated **user**.

        :param credentials:
            The **user's** :class:`.Credentials` (serialized or normal).

        :param str url:
            The URL of the **protected resource**.

        :param str method:
            HTTP method of the request.

        :param dict headers:
            HTTP headers of the request.

        :param str body:
            Body of ``POST``, ``PUT`` and ``PATCH`` requests.

        :param int max_redirects:
            Maximum number of HTTP redirects to follow.

        :param function content_parser:
            A function to be used to parse the :attr:`.Response.data`
            from :attr:`.Response.content`.

        :returns:
            :class:`.Response`

        """

        if not self.user and not self.credentials:
            raise CredentialsError(u'There is no authenticated user!')

        headers = headers or {}

        self._log(
            logging.INFO,
            u'Accessing protected resource {0}.'.format(url))

        request_elements = self.create_request_elements(
            request_type=self.PROTECTED_RESOURCE_REQUEST_TYPE,
            credentials=self.credentials,
            url=url,
            body=body,
            params=params,
            headers=headers,
            method=method
        )

        response = self._fetch(*request_elements,
                               max_redirects=max_redirects,
                               content_parser=content_parser)

        self._log(
            logging.INFO,
            u'Got response. HTTP status = {0}.'.format(
                response.status))
        return response


Instruction:
Explain what the following Python 3 code does
def async_access(self, *args, **kwargs):

        return authomatic.core.Future(self.access, *args, **kwargs)

Response: Same as authomatic. core. access but runs asynchronously in a separate thread.


Instruction:
Create a Python 3 function to
update the user object.

Response:
def update_user(self):
        """
        Updates the :attr:`.BaseProvider.user`.

        .. warning::
            Fetches the :attr:`.user_info_url`!

        :returns:
            :class:`.UserInfoResponse`

        """
        if self.user_info_url:
            response = self._access_user_info()
            self.user = self._update_or_create_user(response.data,
                                                    content=response.content)
            return authomatic.core.UserInfoResponse(self.user,
                                                    response.httplib_response)


Instruction:
Write a Python 3 function for
creating the authorization header if the provider supports it.

Response:
def _authorization_header(cls, credentials):
        """
        Creates authorization headers if the provider supports it. See:
        http://en.wikipedia.org/wiki/Basic_access_authentication.

        :param credentials:
            :class:`.Credentials`

        :returns:
            Headers as :class:`dict`.

        """

        if cls._x_use_authorization_header:
            res = ':'.join(
                (credentials.consumer_key,
                 credentials.consumer_secret))
            res = base64.b64encode(six.b(res)).decode()
            return {'Authorization': 'Basic {0}'.format(res)}
        else:
            return {}


Instruction:
How would you code a function in Python 3 to
validate the consumer key and secret

Response:
def _check_consumer(self):
        """
        Validates the :attr:`.consumer`.
        """

        # 'magic' using _kwarg method
        # pylint:disable=no-member
        if not self.consumer.key:
            raise ConfigError(
                'Consumer key not specified for provider {0}!'.format(
                    self.name))

        if not self.consumer.secret:
            raise ConfigError(
                'Consumer secret not specified for provider {0}!'.format(
                    self.name))


Instruction:
Create a Python 3 function to
split given url to base and params converted to list of tuples.

Response:
def _split_url(url):
        """
        Splits given url to url base and params converted to list of tuples.
        """

        split = parse.urlsplit(url)
        base = parse.urlunsplit((split.scheme, split.netloc, split.path, 0, 0))
        params = parse.parse_qsl(split.query, True)

        return base, params


Instruction:
Make a summary of the following Python 3 code
def _access_user_info(self):
        url = self.user_info_url.format(**self.user.__dict__)
        return self.access(url)

Response: Access the user info url.


Instruction:
Write a Python 3 function that can
set the CORS headers for the response object.

Response:
def set_cors_headers(req, resp, context, options):
    """
    Performs the actual evaluation of Sanic-CORS options and actually
    modifies the response object.

    This function is used both in the decorator and the after_request
    callback
    :param sanic.request.Request req:

    """
    try:
        request_context = context.request[id(req)]
    except AttributeError:
        LOG.debug("Cannot find the request context. Is request already finished?")
        return resp
    # If CORS has already been evaluated via the decorator, skip
    evaluated = request_context.get(SANIC_CORS_EVALUATED, False)
    if evaluated:
        LOG.debug('CORS have been already evaluated, skipping')
        return resp

    # `resp` can be None in the case of using Websockets
    # however this case should have been handled in the `extension` and `decorator` methods
    # before getting here. This is a final failsafe check to prevent crashing
    if resp is None:
        return None

    if resp.headers is None:
        resp.headers = CIMultiDict()

    headers_to_set = get_cors_headers(options, req.headers, req.method)

    LOG.debug('Settings CORS headers: %s', str(headers_to_set))

    # dict .extend() does not work on CIDict so
    # iterate over them and add them individually.
    try:
        resp.headers.extend(headers_to_set)
    except Exception as e1:
        for k, v in headers_to_set.items():
            try:
                resp.headers.add(k, v)
            except Exception as e2:
                resp.headers[k] = v
        return resp


Instruction:
Can you tell what is the following Python 3 function doing
def get_app_kwarg_dict(appInstance):
    # In order to support blueprints which do not have a config attribute
    app_config = getattr(appInstance, 'config', {})
    return dict(
        (k.lower().replace('cors_', ''), app_config.get(k))
        for k in CONFIG_OPTIONS
        if app_config.get(k) is not None
    )

Response: Returns the dictionary of CORS specific app configurations.


Instruction:
Can you generate the documentation for the following Python 3 function
def flexible_str(obj):
    if obj is None:
        return None
    elif(not isinstance(obj, str)
            and isinstance(obj, collections.abc.Iterable)):
        return ', '.join(str(item) for item in sorted(obj))
    else:
        return str(obj)

Response:
A more flexible str function which intelligently handles stringifying
    strings lists and other iterables.


Instruction:
How would you implement a function in Python 3 that
ensures that an instance is iterable.

Response:
def ensure_iterable(inst):
    """
    Wraps scalars or string types as a list, or returns the iterable instance.
    """
    if isinstance(inst, str):
        return [inst]
    elif not isinstance(inst, collections.abc.Iterable):
        return [inst]
    else:
        return inst


Instruction:
Explain what the following Python 3 code does
def isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0):
    try:
        return math.isclose(a, b, rel_tol=rel_tol, abs_tol=abs_tol)
    except AttributeError:
        # Running on older version of python, fall back to hand-rolled implementation
        if (rel_tol < 0.0) or (abs_tol < 0.0):
            raise ValueError("Tolerances must be non-negative, but are rel_tol: {} and abs_tol: {}".format(rel_tol, abs_tol))
        if math.isnan(a) or math.isnan(b):
            return False  # NaNs are never close to anything, even other NaNs
        if (a == b):
            return True
        if math.isinf(a) or math.isinf(b):
            return False  # Infinity is only close to itself, and we already handled that case
        diff = abs(a - b)
        return (diff <= rel_tol * abs(b)) or (diff <= rel_tol * abs(a)) or (diff <= abs_tol)

Response: Python 3. 4 does not have math. isclose but we have to steal it and add it here.


Instruction:
Can you write a function in Python 3 where it
attempts to deserialize a bytestring into an audiosegment. :param bstr: The bytestring serialized via an audiosegment's serialize() method. :returns: An AudioSegment object deserialized from `bstr`.

Response:
def deserialize(bstr):
    """
    Attempts to deserialize a bytestring into an audiosegment.

    :param bstr: The bytestring serialized via an audiosegment's serialize() method.
    :returns: An AudioSegment object deserialized from `bstr`.
    """
    d = pickle.loads(bstr)
    seg = pickle.loads(d['seg'])
    return AudioSegment(seg, d['name'])


Instruction:
How would you implement a function in Python 3 that
returns an AudioSegment object from the given file based on its file extension.

Response:
def from_file(path):
    """
    Returns an AudioSegment object from the given file based on its file extension.
    If the extension is wrong, this will throw some sort of error.

    :param path: The path to the file, including the file extension.
    :returns: An AudioSegment instance from the file.
    """
    _name, ext = os.path.splitext(path)
    ext = ext.lower()[1:]
    seg = pydub.AudioSegment.from_file(path, ext)
    return AudioSegment(seg, path)


Instruction:
Can you implement a function in Python 3 that
creates an audio segment from a numpy array.

Response:
def from_numpy_array(nparr, framerate):
    """
    Returns an AudioSegment created from the given numpy array.

    The numpy array must have shape = (num_samples, num_channels).

    :param nparr: The numpy array to create an AudioSegment from.
    :returns: An AudioSegment created from the given array.
    """
    # interleave the audio across all channels and collapse
    if nparr.dtype.itemsize not in (1, 2, 4):
        raise ValueError("Numpy Array must contain 8, 16, or 32 bit values.")
    if len(nparr.shape) == 1:
        arrays = [nparr]
    elif len(nparr.shape) == 2:
        arrays = [nparr[i,:] for i in range(nparr.shape[0])]
    else:
        raise ValueError("Numpy Array must be one or two dimensional. Shape must be: (num_samples, num_channels).")
    interleaved = np.vstack(arrays).reshape((-1,), order='F')
    dubseg = pydub.AudioSegment(interleaved.tobytes(),
                                frame_rate=framerate,
                                sample_width=interleaved.dtype.itemsize,
                                channels=len(interleaved.shape)
                               )
    return AudioSegment(dubseg, "")


Instruction:
Write a Python 3 script for
creating an audio segment filled with pure silence.

Response:
def silent(duration=1000, frame_rate=11025):
    """
    Creates an AudioSegment object of the specified duration/frame_rate filled with digital silence.

    :param duration: The duration of the returned object in ms.
    :param frame_rate: The samples per second of the returned object.
    :returns: AudioSegment object filled with pure digital silence.
    """
    seg = pydub.AudioSegment.silent(duration=duration, frame_rate=frame_rate)
    return AudioSegment(seg, "")


Instruction:
Can you create a Python 3 function that
calculates the SPL measurement of the audio segment.

Response:
def spl(self):
        """
        Sound Pressure Level - defined as 20 * log10(p/p0),
        where p is the RMS of the sound wave in Pascals and p0 is
        20 micro Pascals.

        Since we would need to know calibration information about the
        microphone used to record the sound in order to transform
        the PCM values of this audiosegment into Pascals, we can't really
        give an accurate SPL measurement.

        However, we can give a reasonable guess that can certainly be used
        to compare two sounds taken from the same microphone set up.

        Be wary about using this to compare sounds taken under different recording
        conditions however, except as a simple approximation.

        Returns a scalar float representing the dB SPL of this audiosegment.
        """
        arr = self.to_numpy_array()
        if len(arr) == 0:
            return 0.0
        else:
            rms = self.rms
            ratio = rms / P_REF_PCM
            return 20.0 * np.log10(ratio + 1E-9)


Instruction:
Write a Python 3 function for
returning a numpy array of shape (nfilters, nsamples), where each row of data is the result of bandpass filtering the audiosegment around a particular frequency. The frequencies are spaced from `lower_bound_hz` to `upper_bound_hz` and are returned with the np array. The particular spacing of the frequencies depends on `mode`, which can be either: 'linear', 'mel', or 'log'. .. note:: This method is an approximation of a gammatone filterbank until I get around to writing an actual gammatone filterbank function. .. code-block:: python # Example usage import audiosegment import matplotlib.pyplot as plt import numpy as np def visualize(spect, frequencies, title=""): # Visualize the result of calling seg.filter_bank() for any number of filters i = 0 for freq, (index, row) in zip(frequencies[::-1], enumerate(spect[::-1, :])): plt.subplot(spect.shape[0], 1, index + 1) if i == 0: plt.title(title) i += 1 plt.ylabel("{0:.0f}".format(freq)) plt.plot(row) plt.show() seg = audiosegment.from_file("some_audio.wav").resample(sample_rate_Hz=24000, sample_width=2, channels=1) spec, frequencies = seg.filter_bank(nfilters=5) visualize(spec, frequencies) .. image:: images/filter_bank.png :param lower_bound_hz: The lower bound of the frequencies to use in the bandpass filters. :param upper_bound_hz: The upper bound of the frequencies to use in the bandpass filters. :param nfilters: The number of filters to apply. This will determine which frequencies are used as well, as they are interpolated between `lower_bound_hz` and `upper_bound_hz` based on `mode`. :param mode: The way the frequencies are spaced. Options are: `linear`, in which case the frequencies are linearly interpolated between `lower_bound_hz` and `upper_bound_hz`, `mel`, in which case the mel frequencies are used, or `log`, in which case they are log-10 spaced. :returns: A numpy array of the form (nfilters, nsamples), where each row is the audiosegment, bandpass-filtered around a particular frequency, and the list of frequencies. I.e., returns (spec, freqs).

Response:
def filter_bank(self, lower_bound_hz=50, upper_bound_hz=8E3, nfilters=128, mode='mel'):
        """
        Returns a numpy array of shape (nfilters, nsamples), where each
        row of data is the result of bandpass filtering the audiosegment
        around a particular frequency. The frequencies are
        spaced from `lower_bound_hz` to `upper_bound_hz` and are returned with
        the np array. The particular spacing of the frequencies depends on `mode`,
        which can be either: 'linear', 'mel', or 'log'.

        .. note:: This method is an approximation of a gammatone filterbank
                  until I get around to writing an actual gammatone filterbank
                  function.

        .. code-block:: python

            # Example usage
            import audiosegment
            import matplotlib.pyplot as plt
            import numpy as np

            def visualize(spect, frequencies, title=""):
                # Visualize the result of calling seg.filter_bank() for any number of filters
                i = 0
                for freq, (index, row) in zip(frequencies[::-1], enumerate(spect[::-1, :])):
                    plt.subplot(spect.shape[0], 1, index + 1)
                    if i == 0:
                        plt.title(title)
                        i += 1
                    plt.ylabel("{0:.0f}".format(freq))
                    plt.plot(row)
                plt.show()

            seg = audiosegment.from_file("some_audio.wav").resample(sample_rate_Hz=24000, sample_width=2, channels=1)
            spec, frequencies = seg.filter_bank(nfilters=5)
            visualize(spec, frequencies)

        .. image:: images/filter_bank.png

        :param lower_bound_hz:  The lower bound of the frequencies to use in the bandpass filters.
        :param upper_bound_hz:  The upper bound of the frequencies to use in the bandpass filters.
        :param nfilters:        The number of filters to apply. This will determine which frequencies
                                are used as well, as they are interpolated between
                                `lower_bound_hz` and `upper_bound_hz` based on `mode`.
        :param mode:            The way the frequencies are spaced. Options are: `linear`, in which case
                                the frequencies are linearly interpolated between `lower_bound_hz` and
                                `upper_bound_hz`, `mel`, in which case the mel frequencies are used,
                                or `log`, in which case they are log-10 spaced.
        :returns:               A numpy array of the form (nfilters, nsamples), where each row is the
                                audiosegment, bandpass-filtered around a particular frequency,
                                and the list of frequencies. I.e., returns (spec, freqs).
        """
        # Logspace to get all the frequency channels we are after
        data = self.to_numpy_array()
        if mode.lower() == 'mel':
            frequencies = librosa.core.mel_frequencies(n_mels=nfilters, fmin=lower_bound_hz, fmax=upper_bound_hz)
        elif mode.lower() == 'linear':
            frequencies = np.linspace(lower_bound_hz, upper_bound_hz, num=nfilters, endpoint=True)
        elif mode.lower() == 'log':
            start = np.log10(lower_bound_hz)
            stop = np.log10(upper_bound_hz)
            frequencies = np.logspace(start, stop, num=nfilters, endpoint=True, base=10.0)
        else:
            raise ValueError("'mode' must be one of: (mel, linear, or log), but was {}".format(mode))

        # Do a band-pass filter in each frequency
        rows = [filters.bandpass_filter(data, freq*0.8, freq*1.2, self.frame_rate) for freq in frequencies]
        rows = np.array(rows)
        spect = np.vstack(rows)
        return spect, frequencies


Instruction:
How would you explain what the following Python 3 function does
def auditory_scene_analysis(self, debug=False, debugplot=False):
        normalized = self.normalize_spl_by_average(db=60)

        def printd(*args, **kwargs):
            if debug:
                print(*args, **kwargs)

        # Create a spectrogram from a filterbank: [nfreqs, nsamples]
        printd("Making filter bank. This takes a little bit.")
        spect, frequencies = normalized.filter_bank(nfilters=128)  # TODO: replace with correct number from paper

        # Half-wave rectify each frequency channel so that each value is 0 or greater - we are looking to get a temporal
        # envelope in each frequency channel
        printd("Half-wave rectifying")
        with warnings.catch_warnings():  # Ignore the annoying Numpy runtime warning for less than
            warnings.simplefilter("ignore")
            spect[spect < 0] = 0

        # Low-pass filter each frequency channel to remove a bunch of noise - we are only looking for large changes
        printd("Low pass filtering")
        low_boundary = 30
        order = 6
        spect = np.apply_along_axis(filters.lowpass_filter, 1, spect, low_boundary, self.frame_rate, order)

        # Downsample each frequency
        printd("Downsampling")
        downsample_freq_hz = 400
        if self.frame_rate > downsample_freq_hz:
            step = int(round(self.frame_rate / downsample_freq_hz))
            spect = spect[:, ::step]

        # Smoothing - we will smooth across time and frequency to further remove noise.
        # But we need to do it with several different combinations of kernels to get the best idea of what's going on
        # Scales are (sc, st), meaning (frequency scale, time scale)
        scales = [(6, 1/4), (6, 1/14), (1/2, 1/14)]

        # For each (sc, st) scale, smooth across time using st, then across frequency using sc
        gaussian = lambda x, mu, sig: np.exp(-np.power(x - mu, 2.0) / (2 * np.power(sig, 2.0)))
        gaussian_kernel = lambda sig: gaussian(np.linspace(-10, 10, len(frequencies) / 2), 0, sig)
        spectrograms = []
        printd("For each scale...")
        for sc, st in scales:
            printd("  -> Scale:", sc, st)
            printd("    -> Time and frequency smoothing")
            time_smoothed = np.apply_along_axis(filters.lowpass_filter, 1, spect, 1/st, downsample_freq_hz, 6)
            freq_smoothed = np.apply_along_axis(np.convolve, 0, time_smoothed, gaussian_kernel(sc), 'same')

            # Remove especially egregious artifacts
            printd("    -> Removing egregious filtering artifacts")
            with warnings.catch_warnings():
                warnings.simplefilter("ignore")
                freq_smoothed[freq_smoothed > 1E3] = 1E3
                freq_smoothed[freq_smoothed < -1E3] = -1E3
            spectrograms.append(freq_smoothed)

        # Onset/Offset Detection and Matching
        segmasks = []
        printd("For each scale...")
        for spect, (sc, st) in zip(spectrograms, scales):
            printd("  -> Scale:", sc, st)
            printd("    -> Getting the onsets")
            # Compute sudden upward changes in spect, these are onsets of events
            onsets, gradients = asa._compute_peaks_or_valleys_of_first_derivative(spect)

            # Compute sudden downward changes in spect, these are offsets of events
            printd("    -> Getting the offsets")
            offsets, _ = asa._compute_peaks_or_valleys_of_first_derivative(spect, do_peaks=False)

            # Correlate offsets with onsets so that we have a 1:1 relationship
            printd("    -> Lining up the onsets and offsets")
            offsets = asa._correlate_onsets_and_offsets(onsets, offsets, gradients)

            # Create onset/offset fronts
            # Do this by connecting onsets across frequency channels if they occur within 20ms of each other
            printd("    -> Create vertical contours (fronts)")
            onset_fronts = asa._form_onset_offset_fronts(onsets, sample_rate_hz=downsample_freq_hz, threshold_ms=20)
            offset_fronts = asa._form_onset_offset_fronts(offsets, sample_rate_hz=downsample_freq_hz, threshold_ms=20)

            # Break poorly matched onset fronts
            printd("    -> Breaking onset fronts between poorly matched frequencies")
            asa._break_poorly_matched_fronts(onset_fronts)

            printd("    -> Getting segmentation mask")
            segmentation_mask = asa._match_fronts(onset_fronts, offset_fronts, onsets, offsets, debug=debug)
            segmasks.append(segmentation_mask)
            break  # TODO: We currently don't bother using the multiscale integration, so we should only do one of the scales

        # Multiscale Integration, seems to conglomerate too well and take too long
        #finished_segmentation_mask = asa._integrate_segmentation_masks(segmasks)  # TODO: doesn't work well and takes too long.
        finished_segmentation_mask = segmasks[0]
        if debugplot:
            asa.visualize_segmentation_mask(finished_segmentation_mask, spect, frequencies)

        # Change the segmentation mask's domain to that of the STFT, so we can invert it into a wave form
        ## Get the times
        times = np.arange(2 * downsample_freq_hz * len(self) / MS_PER_S)
        printd("Times vs segmentation_mask's times:", times.shape, finished_segmentation_mask.shape[1])

        ## Determine the new times and frequencies
        nsamples_for_each_fft = 2 * finished_segmentation_mask.shape[0]
        printd("Converting self into STFT")
        stft_frequencies, stft_times, stft = signal.stft(self.to_numpy_array(), self.frame_rate, nperseg=nsamples_for_each_fft)
        printd("STFTs shape:", stft.shape)
        printd("Frequencies:", stft_frequencies.shape)
        printd("Times:", stft_times.shape)

        ## Due to rounding, the STFT frequency may be one more than we want
        if stft_frequencies.shape[0] > finished_segmentation_mask.shape[0]:
            stft_frequencies = stft_frequencies[:finished_segmentation_mask.shape[0]]
            stft = stft[:stft_frequencies.shape[0], :]

        ## Downsample one into the other's times (if needed)
        finished_segmentation_mask, times, stft, stft_times = asa._downsample_one_or_the_other(stft, stft_times, finished_segmentation_mask, times)
        printd("Adjusted STFTs shape:", stft.shape)
        printd("Adjusted STFTs frequencies:", stft_frequencies.shape)
        printd("Adjusted STFTs times:", stft_times.shape)
        printd("Segmentation mask:", finished_segmentation_mask.shape)

        ## Interpolate to map the data into the new domain
        printd("Attempting to map mask of shape", finished_segmentation_mask.shape, "into shape", (stft_frequencies.shape[0], stft_times.shape[0]))
        finished_segmentation_mask = asa._map_segmentation_mask_to_stft_domain(finished_segmentation_mask, times, frequencies, stft_times, stft_frequencies)

        # Separate the mask into a bunch of single segments
        printd("Separating masks and throwing out inconsequential ones...")
        masks = asa._separate_masks(finished_segmentation_mask)
        printd("N separate masks:", len(masks))

        # If we couldn't segment into masks after thresholding,
        # there wasn't more than a single audio stream
        # Just return us as the only audio stream
        if len(masks) == 0:
            clone = from_numpy_array(self.to_numpy_array(), self.frame_rate)
            return [clone]

        # TODO: Group masks that belong together... somehow...

        # Now multiprocess the rest, since it takes forever and is easily parallelizable
        try:
            ncpus = multiprocessing.cpu_count()
        except NotImplementedError:
            ncpus = 2

        ncpus = len(masks) if len(masks) < ncpus else ncpus

        chunks = np.array_split(masks, ncpus)
        assert len(chunks) == ncpus
        queue = multiprocessing.Queue()
        printd("Using {} processes to convert {} masks into linear STFT space and then time domain.".format(ncpus, len(masks)))
        for i in range(ncpus):
            p = multiprocessing.Process(target=asa._asa_task,
                                        args=(queue, chunks[i], stft, self.sample_width, self.frame_rate, nsamples_for_each_fft),
                                        daemon=True)
            p.start()

        results = []
        dones = []
        while len(dones) < ncpus:
            item = queue.get()
            if type(item) == str and item == "DONE":
                dones.append(item)
            else:
                wav = from_numpy_array(item, self.frame_rate)
                results.append(wav)

        return results

Response: This method performs the actual auditory scene analysis of the audio segments in the audio source.


Instruction:
Write a Python 3 script to
detect voice segment of the audio file.

Response:
def detect_voice(self, prob_detect_voice=0.5):
        """
        Returns self as a list of tuples:
        [('v', voiced segment), ('u', unvoiced segment), (etc.)]

        The overall order of the AudioSegment is preserved.

        :param prob_detect_voice: The raw probability that any random 20ms window of the audio file
                                  contains voice.
        :returns: The described list.
        """
        assert self.frame_rate in (48000, 32000, 16000, 8000), "Try resampling to one of the allowed frame rates."
        assert self.sample_width == 2, "Try resampling to 16 bit."
        assert self.channels == 1, "Try resampling to one channel."

        class model_class:
            def __init__(self, aggressiveness):
                self.v = webrtcvad.Vad(int(aggressiveness))

            def predict(self, vector):
                if self.v.is_speech(vector.raw_data, vector.frame_rate):
                    return 1
                else:
                    return 0

        model = model_class(aggressiveness=2)
        pyesno = 0.3  # Probability of the next 20 ms being unvoiced given that this 20 ms was voiced
        pnoyes = 0.2  # Probability of the next 20 ms being voiced given that this 20 ms was unvoiced
        p_realyes_outputyes = 0.4  # WebRTCVAD has a very high FP rate - just because it says yes, doesn't mean much
        p_realyes_outputno  = 0.05  # If it says no, we can be very certain that it really is a no
        p_yes_raw = prob_detect_voice
        filtered = self.detect_event(model=model,
                                     ms_per_input=20,
                                     transition_matrix=(pyesno, pnoyes),
                                     model_stats=(p_realyes_outputyes, p_realyes_outputno),
                                     event_length_s=0.25,
                                     prob_raw_yes=p_yes_raw)
        ret = []
        for tup in filtered:
            t = ('v', tup[1]) if tup[0] == 'y' else ('u', tup[1])
            ret.append(t)
        return ret


Instruction:
How would you explain what the following Python 3 function does
def dice(self, seconds, zero_pad=False):
        try:
            total_s = sum(seconds)
            if not (self.duration_seconds <= total_s + 1 and self.duration_seconds >= total_s - 1):
                raise ValueError("`seconds` does not sum to within one second of the duration of this AudioSegment.\
                                 given total seconds: %s and self.duration_seconds: %s" % (total_s, self.duration_seconds))
            starts = []
            stops = []
            time_ms = 0
            for dur in seconds:
                starts.append(time_ms)
                time_ms += dur * MS_PER_S
                stops.append(time_ms)
            zero_pad = False
        except TypeError:
            # `seconds` is not a list
            starts = range(0, int(round(self.duration_seconds * MS_PER_S)), int(round(seconds * MS_PER_S)))
            stops = (min(self.duration_seconds * MS_PER_S, start + seconds * MS_PER_S) for start in starts)
        outs = [self[start:stop] for start, stop in zip(starts, stops)]
        out_lens = [out.duration_seconds for out in outs]
        # Check if our last slice is within one ms of expected - if so, we don't need to zero pad
        if zero_pad and not (out_lens[-1] <= seconds * MS_PER_S + 1 and out_lens[-1] >= seconds * MS_PER_S - 1):
            num_zeros = self.frame_rate * (seconds * MS_PER_S - out_lens[-1])
            outs[-1] = outs[-1].zero_extend(num_samples=num_zeros)
        return outs

Response: Returns a list of audio segments that are at most the given number of seconds.