Coverage for sources/appcore/asyncf.py: 100%

40 statements  

« prev     ^ index     » next       coverage.py v7.17.0, created at 2026-10-27 19:39 +0000

1# vim: set filetype=python fileencoding=utf-8: 

2# -*- coding: utf-8 -*- 

3 

4#============================================================================# 

5# # 

6# Licensed under the Apache License, Version 2.0 (the "License"); # 

7# you may not use this file except in compliance with the License. # 

8# You may obtain a copy of the License at # 

9# # 

10# http://www.apache.org/licenses/LICENSE-2.0 # 

11# # 

12# Unless required by applicable law or agreed to in writing, software # 

13# distributed under the License is distributed on an "AS IS" BASIS, # 

14# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

15# See the License for the specific language governing permissions and # 

16# limitations under the License. # 

17# # 

18#============================================================================# 

19 

20 

21''' Helper functions for async execution. ''' 

22 

23 

24from . import __ 

25from . import exceptions as _exceptions 

26from . import generics as _generics 

27 

28 

29@__.typx.overload 

30async def gather_async( # pragma: no cover 

31 *operands: __.typx.Any, 

32 return_exceptions: __.typx.Literal[ True ], 

33 error_message: str = 'Failure of async operations.', 

34 ignore_nonawaitables: bool = False, 

35) -> tuple[ _generics.GenericResult, ... ]: ... 

36 

37 

38@__.typx.overload 

39async def gather_async( # noqa: F811 # pragma: no cover 

40 *operands: __.typx.Any, 

41 return_exceptions: __.typx.Literal[ False ] = False, 

42 error_message: str = 'Failure of async operations.', 

43 ignore_nonawaitables: bool = False, 

44) -> tuple[ __.typx.Any, ... ]: ... 

45 

46 

47async def gather_async( # noqa: F811 

48 *operands: __.typx.Any, 

49 return_exceptions: __.typx.Annotated[ 

50 bool, 

51 __.ddoc.Doc( ''' Raw or wrapped results. Wrapped, if true. ''' ) 

52 ] = False, 

53 error_message: str = 'Failure of async operations.', 

54 ignore_nonawaitables: __.typx.Annotated[ 

55 bool, 

56 __.ddoc.Doc( 

57 ''' Ignore or error on non-awaitables. Ignore, if true. ''' ) 

58 ] = False, 

59) -> tuple[ __.typx.Any, ... ]: 

60 ''' Gathers results from invocables concurrently and asynchronously. ''' 

61 if ignore_nonawaitables: 

62 results = await _gather_async_permissive( operands ) 

63 else: 

64 results = await _gather_async_strict( operands ) 

65 if return_exceptions: return tuple( results ) 

66 errors = tuple( result.error for result in results if result.is_error( ) ) 

67 if errors: raise ExceptionGroup( error_message, errors ) 

68 return tuple( result.extract( ) for result in results ) 

69 

70 

71async def intercept_error_async( 

72 awaitable: __.cabc.Awaitable[ __.typx.Any ] 

73) -> _generics.Result[ object, Exception ]: 

74 ''' Converts unwinding exceptions to error results. 

75 

76 Exceptions, which are not instances of :py:exc:`Exception` or one of 

77 its subclasses, are allowed to propagate. In particular, 

78 :py:exc:`KeyboardInterrupt` and :py:exc:`SystemExit` must be allowed 

79 to propagate to be consistent with :py:class:`asyncio.TaskGroup` 

80 behavior. 

81 

82 Helpful when working with :py:func:`asyncio.gather`, for example, 

83 because exceptions can be distinguished from computed values 

84 and collected together into an exception group. 

85 

86 In general, it is a bad idea to swallow exceptions. In this case, 

87 the intent is to add them into an exception group for continued 

88 propagation. 

89 ''' 

90 try: return _generics.Value( await awaitable ) 

91 except Exception as exc: 

92 return _generics.Error( exc ) 

93 

94 

95async def _gather_async_permissive( 

96 operands: __.cabc.Sequence[ __.typx.Any ] 

97) -> __.cabc.Sequence[ __.typx.Any ]: 

98 from asyncio import gather # TODO? Python 3.11: TaskGroup 

99 awaitables: dict[ int, __.cabc.Awaitable[ __.typx.Any ] ] = { } 

100 results: list[ _generics.GenericResult ] = [ ] 

101 for i, operand in enumerate( operands ): 

102 if isinstance( operand, __.cabc.Awaitable ): 

103 awaitables[ i ] = ( 

104 intercept_error_async( __.typx.cast( 

105 __.cabc.Awaitable[ __.typx.Any ], operand ) ) ) 

106 results.append( _generics.Value( None ) ) 

107 else: results.append( _generics.Value( operand ) ) 

108 results_ = await gather( *awaitables.values( ) ) 

109 for i, result in zip( awaitables.keys( ), results_ ): 

110 results[ i ] = result 

111 return results 

112 

113 

114async def _gather_async_strict( 

115 operands: __.cabc.Sequence[ __.typx.Any ] 

116) -> __.cabc.Sequence[ __.typx.Any ]: 

117 from asyncio import gather # TODO? Python 3.11: TaskGroup 

118 from inspect import isawaitable, iscoroutine 

119 awaitables: list[ __.cabc.Awaitable[ __.typx.Any ] ] = [ ] 

120 for operand in operands: # Sanity check. 

121 if isawaitable( operand ): continue 

122 for operand_ in operands: # Cleanup. 

123 if iscoroutine( operand_ ): operand_.close( ) 

124 raise _exceptions.AsyncAssertionFailure( operand ) 

125 for operand in operands: 

126 awaitables.append( intercept_error_async( __.typx.cast( # noqa: PERF401 

127 __.cabc.Awaitable[ __.typx.Any ], operand ) ) ) 

128 return await gather( *awaitables ) 

129 

130 

131if __.typx.TYPE_CHECKING: # pragma: no cover 

132 async def _type_check_canary( ) -> None: 

133 ''' Canary function to verify overload type checking works correctly. 

134 

135 This function is never executed but helps ensure that Pyright 

136 correctly understands our gather_async overloads. 

137 ''' 

138 async def dummy_operation( ) -> str: return "test" 

139 

140 operations = ( dummy_operation( ), dummy_operation( ) ) 

141 results = await gather_async( *operations, return_exceptions = True ) 

142 for result in results: 

143 match result: 

144 case _generics.Value( value ): _ = value 

145 case _generics.Error( error ): _ = error 

146 case _: pass 

147 for result in results: 

148 if _generics.is_error( result ): _ = result.error 

149 else: _ = result.extract( ) 

150 values = await gather_async( *operations, return_exceptions = False ) 

151 for value in values: _ = str( value )