Coverage for sources/appcore/asyncf.py: 100%
40 statements
« prev ^ index » next coverage.py v7.17.0, created at 2026-10-27 19:49 +0000
« prev ^ index » next coverage.py v7.17.0, created at 2026-10-27 19:49 +0000
1# vim: set filetype=python fileencoding=utf-8:
2# -*- coding: utf-8 -*-
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#============================================================================#
21''' Helper functions for async execution. '''
24from . import __
25from . import exceptions as _exceptions
26from . import generics as _generics
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, ... ]: ...
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, ... ]: ...
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 )
71async def intercept_error_async(
72 awaitable: __.cabc.Awaitable[ __.typx.Any ]
73) -> _generics.Result[ object, Exception ]:
74 ''' Converts unwinding exceptions to error results.
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.
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.
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 )
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
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 )
131if __.typx.TYPE_CHECKING: # pragma: no cover
132 async def _type_check_canary( ) -> None:
133 ''' Canary function to verify overload type checking works correctly.
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"
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 )