Coverage for nexios\__init__.py: 100%

1""" 

2Implemented based on Starlette version 0.45.3. 

3 

4This module adapts selected components and logic from Starlette to ensure compatibility 

5with our internal architecture, while preserving the async-first design principles and 

6middleware patterns that Starlette is known for. 

7 

8Key inspirations from Starlette include: 

9- ASGI application structure 

10- Middleware handling pattern 

11 

12 

13Note: Adjustments have been made for dependency injection, custom error handling, 

14and simplified routing mechanisms to better suit the Nexios framework architecture. 

15""" 

16 

17from typing import List, Optional, Callable, AsyncContextManager 

18 

19from typing_extensions import Doc, Annotated 

20 

21from .application import NexiosApp 

22from .config import set_config, DEFAULT_CONFIG 

23from .config.base import MakeConfig 

24from .middlewares.core import wrap_middleware 

25from .middlewares.cors import CORSMiddleware 

26from .middlewares.csrf import CSRFMiddleware 

27from .routing import Router, Routes 

28from .session.middleware import SessionMiddleware 

29from .types import ExceptionHandlerType 

30from .dependencies import Depend 

31import warnings 

32 

33 

34def get_application( 

35 config: Annotated[ 

36 MakeConfig, 

37 Doc( 

38 """ 

39 This subclass is derived from the MakeConfig class and is responsible for managing configurations within the Nexios framework. It takes arguments in the form of dictionaries, allowing for structured and flexible configuration handling. By using dictionaries, this subclass makes it easy to pass multiple configuration values at once, reducing complexity and improving maintainability. 

40 

41 One of the key advantages of this approach is its ability to dynamically update and modify settings without requiring changes to the core codebase. This is particularly useful in environments where configurations need to be frequently adjusted, such as database settings, API credentials, or feature flags. The subclass can also validate the provided configuration data, ensuring that incorrect or missing values are handled properly. 

42 

43 Additionally, this design allows for merging and overriding configurations, making it adaptable for various use cases. Whether used for small projects or large-scale applications, this subclass ensures that configuration management remains efficient and scalable. By extending MakeConfig, it leverages existing functionality while adding new capabilities tailored to Nexios. This makes it an essential component for maintaining structured and well-organized application settings. 

44 """ 

45 ), 

46 ] = DEFAULT_CONFIG, 

47 title: Annotated[ 

48 Optional[str], 

49 Doc( 

50 """ 

51 The title of the API, used in the OpenAPI documentation. 

52 """ 

53 ), 

54 ] = None, 

55 version: Annotated[ 

56 Optional[str], 

57 Doc( 

58 """ 

59 The version of the API, used in the OpenAPI documentation. 

60 """ 

61 ), 

62 ] = None, 

63 description: Annotated[ 

64 Optional[str], 

65 Doc( 

66 """ 

67 A brief description of the API, used in the OpenAPI documentation. 

68 """ 

69 ), 

70 ] = None, 

71 server_error_handler: Annotated[ 

72 Optional[ExceptionHandlerType], 

73 Doc( 

74 """ 

75 A function in Nexios responsible for handling server-side exceptions by logging errors, reporting issues, or initiating recovery mechanisms. It prevents crashes by intercepting unexpected failures, ensuring the application remains stable and operational. This function provides a structured approach to error management, allowing developers to define custom handling strategies such as retrying failed requests, sending alerts, or gracefully degrading functionality. By centralizing error processing, it improves maintainability and observability, making debugging and monitoring more efficient. Additionally, it ensures that critical failures do not disrupt the entire system, allowing services to continue running while appropriately managing faults and failures.""" 

76 ), 

77 ] = None, 

78 lifespan: Optional[Callable[["NexiosApp"], AsyncContextManager[bool]]] = None, 

79 routes: Optional[List[Routes]] = None, 

80) -> NexiosApp: 

81 """ 

82 Initializes and returns a `Nexios` application instance, serving as the core entry point for building web applications. 

83 

84 Nexios is a lightweight, asynchronous Python framework designed for speed, flexibility, and ease of use. 

85 This function sets up the necessary configurations and routing mechanisms, allowing developers 

86 to define routes, handle requests, and manage responses efficiently. 

87 

88 ## Example Usage 

89 

90 ```python 

91 from nexios import Nexios 

92 config = MakeConfig({ 

93 "debug" : True 

94 }) 

95 app = get_application(config = config) 

96 ``` 

97 

98 Returns: 

99 Nexios: An instance of the Nexios application, ready to register routes and handle requests. 

100 

101 See Also: 

102 - [Nexios Documentation](https://example.com/nexios-docs) 

103 """ 

104 warnings.warn( 

105 "get_application is deprecated. Please use NexiosApp instead.", 

106 DeprecationWarning, 

107 ) 

108 set_config(config) 

109 app = NexiosApp( 

110 middlewares=[ 

111 wrap_middleware(CORSMiddleware()), 

112 wrap_middleware(SessionMiddleware()), 

113 wrap_middleware(CSRFMiddleware()), 

114 ], 

115 server_error_handler=server_error_handler, 

116 config=config, 

117 title=title, 

118 version=version, 

119 description=description, 

120 lifespan=lifespan, 

121 ) 

122 

123 return app 

124 

125 

126__all__ = ["MakeConfig", "Router", "NexiosApp", "get_application", "Depend"]