apifrom.decorators ================== Decorators for the APIFromAnything library. This package provides decorators that can be used to enhance API endpoints with additional functionality. .. py:currentmodule:: apifrom.decorators Overview -------- **Classes** * :py:class:`Web` * :py:class:`WebOptimize` **Functions** * :py:func:`api` Classes ------- .. py:class:: Web(title = None, description = None, theme = 'default', template = None) Decorator that enhances API endpoints with HTML rendering capabilities. When an endpoint decorated with @Web is accessed with an Accept header that includes 'text/html' (e.g., from a web browser), the response will be rendered as HTML. Otherwise, the response will be returned as JSON (the default API behavior). This makes API endpoints more user-friendly when accessed directly from a web browser, while maintaining their programmatic API functionality. .. attribute:: title The title to display in the HTML page :type: str .. attribute:: description A description of the endpoint to display in the HTML :type: str .. attribute:: theme The theme to use for styling ('default', 'dark', 'light') :type: str .. attribute:: template Optional path to a custom HTML template :type: str .. admonition:: Example ```python from apifrom.core.app import API from apifrom.decorators.web import Web app = API() @app.api('/users') @Web(title="Users API", description="Get a list of users") def get_users(request): return [ {"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}, {"id": 3, "name": "Charlie"} ] ``` Initialize the Web decorator. :param title: The title to display in the HTML page :param description: A description of the endpoint to display in the HTML :param theme: The theme to use for styling ('default', 'dark', 'light') :param template: Optional path to a custom HTML template .. :: description .. :: template .. :: theme .. :: title .. method:: __call__(func) Apply the decorator to the function. :param func: The function to decorate :returns: The decorated function .. method:: _format_value(value) Format a value for HTML display. :param value: The value to format :returns: The formatted value .. method:: _get_theme_styles() Get the CSS styles for the current theme. :returns: The CSS styles for the theme .. method:: _render_dict(data) Render a dictionary as HTML. :param data: The dictionary to render :returns: The HTML representation of the dictionary .. method:: _render_html(data) Render the data as HTML. :param data: The data to render :returns: The HTML representation of the data .. method:: _render_list(data) Render a list as HTML. :param data: The list to render :returns: The HTML representation of the list .. method:: _render_with_template(data) Render the data using a custom template. :param data: The data to render :returns: The HTML representation of the data using the template .. py:class:: WebOptimize(title = None, description = None, theme = 'default', template = None, enable_profiling = False, enable_caching = False, cache_ttl = 60, enable_connection_pooling = False, pool_name = None, enable_request_coalescing = False, coalesce_window_time = 0.5, coalesce_max_requests = 10, enable_batch_processing = False, batch_size = 10, batch_wait_time = 0.5):bases: apifrom.decorators.web.Web Decorator that combines the Web decorator with performance optimization features. This decorator enhances API endpoints with HTML rendering capabilities and performance optimization features like profiling, caching, connection pooling, request coalescing, and batch processing. .. attribute:: title The title to display in the HTML page :type: str .. attribute:: description A description of the endpoint to display in the HTML :type: str .. attribute:: theme The theme to use for styling ('default', 'dark', 'light') :type: str .. attribute:: template Optional path to a custom HTML template :type: str .. attribute:: enable_profiling Whether to enable profiling :type: bool .. attribute:: enable_caching Whether to enable caching :type: bool .. attribute:: cache_ttl Time-to-live for cached responses in seconds :type: int .. attribute:: enable_connection_pooling Whether to enable connection pooling :type: bool .. attribute:: pool_name Name of the connection pool to use :type: str .. attribute:: enable_request_coalescing Whether to enable request coalescing :type: bool .. attribute:: coalesce_window_time Time window for coalescing requests in seconds :type: float .. attribute:: coalesce_max_requests Maximum number of requests to coalesce :type: int .. attribute:: enable_batch_processing Whether to enable batch processing :type: bool .. attribute:: batch_size Maximum batch size for batch processing :type: int .. attribute:: batch_wait_time Maximum wait time for batch processing in seconds :type: float .. admonition:: Example ```python from apifrom.core.app import API from apifrom.decorators.web_optimize import WebOptimize app = API() @app.api('/users') @WebOptimize( title="Users API", description="Get a list of users", enable_caching=True, cache_ttl=60, enable_profiling=True ) def get_users(request): return [ {"id": 1, "name": "Alice", "email": "alice@example.com"}, {"id": 2, "name": "Bob", "email": "bob@example.com"}, {"id": 3, "name": "Charlie", "email": "charlie@example.com"} ] ``` Initialize the WebOptimize decorator. :param title: The title to display in the HTML page :param description: A description of the endpoint to display in the HTML :param theme: The theme to use for styling ('default', 'dark', 'light') :param template: Optional path to a custom HTML template :param enable_profiling: Whether to enable profiling :param enable_caching: Whether to enable caching :param cache_ttl: Time-to-live for cached responses in seconds :param enable_connection_pooling: Whether to enable connection pooling :param pool_name: Name of the connection pool to use :param enable_request_coalescing: Whether to enable request coalescing :param coalesce_window_time: Time window for coalescing requests in seconds :param coalesce_max_requests: Maximum number of requests to coalesce :param enable_batch_processing: Whether to enable batch processing :param batch_size: Maximum batch size for batch processing :param batch_wait_time: Maximum wait time for batch processing in seconds .. :: _cache_optimizer .. :: _pool_manager .. :: _profiler .. :: batch_size .. :: batch_wait_time .. :: cache_ttl .. :: coalesce_max_requests .. :: coalesce_window_time .. :: enable_batch_processing .. :: enable_caching .. :: enable_connection_pooling .. :: enable_profiling .. :: enable_request_coalescing .. :: pool_name .. method:: __call__(func) Apply the WebOptimize decorator to a function. :param func: The function to decorate :returns: The decorated function .. method:: create_pool(name, min_size = 5, max_size = 20, validate_func = None) :classmethod: Create a connection pool with the specified settings. :param name: Name of the connection pool :param min_size: Minimum number of connections in the pool :param max_size: Maximum number of connections in the pool :param validate_func: Function to validate connections :returns: A ConnectionPool instance .. method:: get_cache_optimizer() :classmethod: Get the class-level cache optimizer instance. .. method:: get_performance_metrics() :classmethod: Get performance metrics from all optimization components. :returns: A dictionary of performance metrics .. method:: get_pool(name) :classmethod: Get a connection pool by name. :param name: Name of the connection pool :returns: A ConnectionPool instance, or None if not found .. method:: get_pool_manager() :classmethod: Get the class-level pool manager instance. .. method:: get_profiler() :classmethod: Get the class-level profiler instance. .. method:: optimize(title = None, description = None, theme = 'default', template = None, enable_profiling = True, enable_caching = True, cache_ttl = 60, enable_connection_pooling = True, pool_name = None, enable_request_coalescing = True, coalesce_window_time = 0.5, coalesce_max_requests = 10, enable_batch_processing = False, batch_size = 10, batch_wait_time = 0.5) :classmethod: Class method to create a WebOptimize decorator with the specified settings. This is a convenience method for creating a WebOptimize decorator with common optimization settings. :param title: The title to display in the HTML page :param description: A description of the endpoint to display in the HTML :param theme: The theme to use for styling ('default', 'dark', 'light') :param template: Optional path to a custom HTML template :param enable_profiling: Whether to enable profiling :param enable_caching: Whether to enable caching :param cache_ttl: Time-to-live for cached responses in seconds :param enable_connection_pooling: Whether to enable connection pooling :param pool_name: Name of the connection pool to use :param enable_request_coalescing: Whether to enable request coalescing :param coalesce_window_time: Time window for coalescing requests in seconds :param coalesce_max_requests: Maximum number of requests to coalesce :param enable_batch_processing: Whether to enable batch processing :param batch_size: Maximum batch size for batch processing :param batch_wait_time: Maximum wait time for batch processing in seconds :returns: A WebOptimize decorator with the specified settings 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.