apifrom.decorators.api
======================


API decorator for APIFromAnything.

This module defines the main API decorator that can be used to expose Python
functions as API endpoints.



.. py:currentmodule:: apifrom.decorators.api

Overview
--------

**Classes**

* :py:class:`ErrorResponse`
* :py:class:`JSONResponse`
* :py:class:`Request`
* :py:class:`Response`


**Functions**

* :py:func:`api`
* :py:func:`deserialize_params`
* :py:func:`get_type_hints_with_extras`
* :py:func:`serialize_response`





Classes
-------

.. py:class:: ErrorResponse(message, status_code = 400, error_code = None, details = None, headers = None):bases: JSONResponse


Error response for APIFromAnything.

   This class represents an HTTP error response with JSON content.

   Initialize a new ErrorResponse instance.

   :param message: The error message.
   :param status_code: The HTTP status code.
   :param error_code: An optional error code.
   :param details: Additional error details.
   :param headers: HTTP headers.






















.. py:class:: JSONResponse(content = None, status_code = 200, headers = None):bases: Response


JSON response for APIFromAnything.

   This class represents an HTTP response with JSON content.

   Initialize a new JSONResponse instance.

   :param content: The response content.
   :param status_code: The HTTP status code.
   :param headers: HTTP headers.






















.. py:class:: Request(request = None, path_params = None, method = None, path = None, query_params = None, headers = None, body = None, client_ip = None)

Request class for APIFromAnything.

   This class wraps a Starlette request and provides methods for accessing
   request data in a convenient way.

   .. attribute:: _request

      The underlying Starlette request.

   .. attribute:: path_params

      Path parameters extracted from the URL.

   .. attribute:: query_params

      Query parameters extracted from the URL.

   .. attribute:: headers

      HTTP headers.

   .. attribute:: method

      HTTP method.

   .. attribute:: path

      Request path.

   .. attribute:: _body

      Cached request body.

   Initialize a new Request instance.

   :param request: The underlying Starlette request.
   :param path_params: Path parameters extracted from the URL.
   :param method: The HTTP method.
   :param path: The request path.
   :param query_params: Query parameters.
   :param headers: HTTP headers.
   :param body: Request body.
   :param client_ip: Client IP address.


















.. py:class:: Response(content = None, status_code = 200, headers = None, content_type = 'application/json')

Response class for APIFromAnything.

   This class represents an HTTP response and provides methods for setting
   response data, status code, and headers.

   .. attribute:: content

      The response content.

   .. attribute:: status_code

      The HTTP status code.

   .. attribute:: headers

      HTTP headers.

   .. attribute:: content_type

      The content type of the response.

   Initialize a new Response instance.

   :param content: The response content.
   :param status_code: The HTTP status code.
   :param headers: HTTP headers.
   :param content_type: The content type of the response.























Functions
---------

.. py:function:: api(route = None, method = 'GET', name = None, description = None, tags = None, response_model = None, status_code = 200, deprecated = False, include_in_schema = True, **kwargs)


Decorator to expose a Python function as an API endpoint.

   :param route: The route for the endpoint. If None, derived from function name.
   :param method: The HTTP method for the endpoint.
   :param name: The name for the endpoint. If None, derived from function name.
   :param description: The description for the endpoint.
   :param tags: Tags for the endpoint.
   :param response_model: The response model for the endpoint.
   :param status_code: The default status code for successful responses.
   :param deprecated: Whether the endpoint is deprecated.
   :param include_in_schema: Whether to include the endpoint in the API schema.
   :param \*\*kwargs: Additional arguments to pass to the router.

   :returns: A decorator function.


.. py:function:: deserialize_params(params, func, type_hints = None)


Deserialize parameters for a function call.

   :param params: The parameters to deserialize.
   :param func: The function or signature to deserialize parameters for.
   :param type_hints: Optional type hints. If not provided, they will be extracted from the function.

   :returns: The deserialized parameters.


.. py:function:: get_type_hints_with_extras(obj)


Get type hints for a callable, including return type.

   This function extends typing.get_type_hints to include additional information
   about the types, such as whether they are optional.

   :param obj: The callable to get type hints for.

   :returns: A dictionary mapping parameter names to their types.


.. py:function:: serialize_response(result)


Serialize a function result for an API response.

   :param result: The function result to serialize.

   :returns: A JSON-compatible representation of the result.