# This Software (Dioptra) is being made available as a public service by the
# National Institute of Standards and Technology (NIST), an Agency of the United
# States Department of Commerce. This software was developed in part by employees of
# NIST and in part by NIST contractors. Copyright in portions of this software that
# were developed by NIST contractors has been licensed or assigned to NIST. Pursuant
# to Title 17 United States Code Section 105, works of NIST employees are not
# subject to copyright protection in the United States. However, NIST may hold
# international copyright in software created by its employees and domestic
# copyright (or licensing rights) in portions of software that were assigned or
# licensed to NIST. To the extent that NIST holds copyright in this software, it is
# being made available under the Creative Commons Attribution 4.0 International
# license (CC BY 4.0). The disclaimers of the CC BY 4.0 license apply to all parts
# of the software developed or licensed by NIST.
#
# ACCESS THE FULL CC BY 4.0 LICENSE HERE:
# https://creativecommons.org/licenses/by/4.0/legalcode
"""A module of utility functions that are used across multiple endpoints.

.. |Namespace| replace:: :py:class:`~flask_restx.Namespace`
.. |ParametersSchema| replace:: :py:class:`~.ParametersSchema`
.. |RequestParser| replace:: :py:class:`~flask_restx.reqparse.RequestParser`
.. |Resource| replace:: :py:class:`~flask_restx.Resource`
"""

from typing import List

from flask_restx import Namespace
from flask_restx.reqparse import RequestParser
from typing_extensions import TypedDict


class ParametersSchema(TypedDict, total=False):
    """A schema of the parameters that can be passed to the |RequestParser|."""

    name: str
    type: object
    location: str
    help: str


def as_api_parser(
    api: Namespace, parameters_schema: List[ParametersSchema]
) -> RequestParser:
    """Creates a |RequestParser| from a list of |ParametersSchema| dictionaries.

    The primary use case for this utility function is to convert a submission form
    schema so that it can be passed to an `@api.expects` decorator and populate the
    form's fields in the Swagger documentation.

    Args:
        api: An endpoint's |Namespace| used for grouping |Resource|s.
        parameters_schema: A list of |ParametersSchema| dictionaries to add as arguments
            to `api.parser()`.

    Returns:
        A |RequestParser| object.
    """
    parser: RequestParser = api.parser()

    for form_kwargs in parameters_schema:
        parser.add_argument(**form_kwargs)

    return parser
