Skip to content

trcks.oop.AwaitableWrapper

Bases: _AwaitableWrapper[_T_co]

Type-safe and immutable wrapper for collections.abc.Awaitable objects.

The wrapped collections.abc.Awaitable can be accessed via the attribute trcks.oop.AwaitableWrapper.core. The trcks.oop.AwaitableWrapper.map* methods allow method chaining. The trcks.oop.AwaitableWrapper.tap* methods allow for side effects without changing the wrapped object.

Example 
>>> import asyncio
>>> from trcks.oop import AwaitableWrapper
>>> async def read_from_disk() -> str:
...     await asyncio.sleep(0.001)
...     input_ = "Hello, world!"
...     print(f"Read '{input_}' from disk.")
...     return input_
...
>>> def transform(s: str) -> str:
...     return f"Length: {len(s)}"
...
>>> async def write_to_disk(s: str) -> None:
...     await asyncio.sleep(0.001)
...     print(f"Wrote '{s}' to disk.")
...
>>> async def main() -> str:
...     awaitable_str = read_from_disk()
...     return await (
...         AwaitableWrapper
...         .construct_from_awaitable(awaitable_str)
...         .map(transform)
...         .tap_to_awaitable(write_to_disk)
...         .core
...     )
...
>>> output = asyncio.run(main())
Read 'Hello, world!' from disk.
Wrote 'Length: 13' to disk.
>>> output
'Length: 13'
Source code in src/trcks/oop.py 
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
class AwaitableWrapper(_AwaitableWrapper[_T_co]):
    """Type-safe and immutable wrapper for [collections.abc.Awaitable][] objects.

    The wrapped [collections.abc.Awaitable][] can be accessed
    via the attribute `trcks.oop.AwaitableWrapper.core`.
    The `trcks.oop.AwaitableWrapper.map*` methods allow method chaining.
    The `trcks.oop.AwaitableWrapper.tap*` methods allow for side effects
    without changing the wrapped object.

    Example:
        >>> import asyncio
        >>> from trcks.oop import AwaitableWrapper
        >>> async def read_from_disk() -> str:
        ...     await asyncio.sleep(0.001)
        ...     input_ = "Hello, world!"
        ...     print(f"Read '{input_}' from disk.")
        ...     return input_
        ...
        >>> def transform(s: str) -> str:
        ...     return f"Length: {len(s)}"
        ...
        >>> async def write_to_disk(s: str) -> None:
        ...     await asyncio.sleep(0.001)
        ...     print(f"Wrote '{s}' to disk.")
        ...
        >>> async def main() -> str:
        ...     awaitable_str = read_from_disk()
        ...     return await (
        ...         AwaitableWrapper
        ...         .construct_from_awaitable(awaitable_str)
        ...         .map(transform)
        ...         .tap_to_awaitable(write_to_disk)
        ...         .core
        ...     )
        ...
        >>> output = asyncio.run(main())
        Read 'Hello, world!' from disk.
        Wrote 'Length: 13' to disk.
        >>> output
        'Length: 13'
    """

    @staticmethod
    def construct(value: _T) -> AwaitableWrapper[_T]:
        """Construct and wrap an [collections.abc.Awaitable][] object from a value.

        Args:
            value: The value to be wrapped.

        Returns:
            A new [trcks.oop.AwaitableWrapper][] instance
                with the wrapped [collections.abc.Awaitable][] object.

        Example:
            >>> import asyncio
            >>> from trcks.oop import AwaitableWrapper
            >>> awaitable_wrapper = AwaitableWrapper.construct("Hello, world!")
            >>> awaitable_wrapper
            AwaitableWrapper(core=<coroutine object ...>)
            >>> asyncio.run(awaitable_wrapper.core_as_coroutine)
            'Hello, world!'
        """
        return AwaitableWrapper(a.construct(value))

    @staticmethod
    def construct_from_awaitable(awtbl: Awaitable[_T]) -> AwaitableWrapper[_T]:
        """Alias for the default constructor.

        Args:
            awtbl: The [collections.abc.Awaitable][] to be wrapped.

        Returns:
            A new [trcks.oop.AwaitableWrapper][] instance
                with the wrapped [collections.abc.Awaitable][] object.

        Example:
            >>> import asyncio
            >>> from trcks.oop import AwaitableWrapper
            >>> async def read_from_disk() -> str:
            ...     return await asyncio.sleep(0.001, result="Hello, world!")
            ...
            >>> awaitable_str = read_from_disk()
            >>> awaitable_wrapper = AwaitableWrapper.construct_from_awaitable(
            ...     awaitable_str
            ... )
            >>> awaitable_wrapper
            AwaitableWrapper(core=<coroutine object read_from_disk at 0x...>)
            >>> asyncio.run(awaitable_wrapper.core_as_coroutine)
            'Hello, world!'
        """
        return AwaitableWrapper(awtbl)

    def map(self, f: Callable[[_T_co], _T]) -> AwaitableWrapper[_T]:
        """Apply a synchronous function
        to the wrapped [collections.abc.Awaitable][] object.

        Args:
            f: The synchronous function to be applied.

        Returns:
            A new [trcks.oop.AwaitableWrapper][] instance with
                the result of the function application.

        Example:
            >>> import asyncio
            >>> from trcks.oop import AwaitableWrapper
            >>> def transform(s: str) -> str:
            ...     return f"Length: {len(s)}"
            ...
            >>> awaitable_wrapper = (
            ...     AwaitableWrapper
            ...     .construct("Hello, world!")
            ...     .map(transform)
            ... )
            >>> awaitable_wrapper
            AwaitableWrapper(core=<coroutine object ...>)
            >>> asyncio.run(awaitable_wrapper.core_as_coroutine)
            'Length: 13'
        """
        return AwaitableWrapper(a.map_(f)(self.core))

    def map_to_awaitable(
        self, f: Callable[[_T_co], Awaitable[_T]]
    ) -> AwaitableWrapper[_T]:
        """Apply an asynchronous function
        to the wrapped [collections.abc.Awaitable][] object.

        Args:
            f: The asynchronous function to be applied.

        Returns:
            A new [trcks.oop.AwaitableWrapper][] instance with
                the result of the function application.

        Example:
            >>> import asyncio
            >>> from trcks.oop import AwaitableWrapper
            >>> async def write_to_disk(output: str) -> None:
            ...     await asyncio.sleep(0.001)
            ...     print(f"Wrote '{output}' to disk.")
            ...
            >>> awaitable_wrapper = (
            ...     AwaitableWrapper
            ...     .construct("Hello, world!")
            ...     .map_to_awaitable(write_to_disk)
            ... )
            >>> awaitable_wrapper
            AwaitableWrapper(core=<coroutine object ...>)
            >>> asyncio.run(awaitable_wrapper.core_as_coroutine)
            Wrote 'Hello, world!' to disk.
        """
        return AwaitableWrapper(a.map_to_awaitable(f)(self.core))

    def map_to_awaitable_result(
        self, f: Callable[[_T_co], AwaitableResult[_F, _S]]
    ) -> AwaitableResultWrapper[_F, _S]:
        """Apply an asynchronous function with return type [trcks.Result][]
        to the wrapped [collections.abc.Awaitable][] object.

        Args:
            f: The asynchronous function to be applied.

        Returns:
            A [trcks.oop.AwaitableResultWrapper][] instance with
                the result of the function application.

        Example:
            >>> import asyncio
            >>> from trcks import Result
            >>> from trcks.oop import AwaitableWrapper
            >>> async def slowly_assert_non_negative(
            ...     x: float,
            ... ) -> Result[str, float]:
            ...     await asyncio.sleep(0.001)
            ...     if x < 0:
            ...         return "failure", "negative value"
            ...     return "success", x
            ...
            >>> awaitable_result_wrapper = (
            ...     AwaitableWrapper
            ...     .construct(42.0)
            ...     .map_to_awaitable_result(slowly_assert_non_negative)
            ... )
            >>> awaitable_result_wrapper
            AwaitableResultWrapper(core=<coroutine object ...>)
            >>> asyncio.run(awaitable_result_wrapper.core_as_coroutine)
            ('success', 42.0)
        """
        return AwaitableResultWrapper.construct_success_from_awaitable(
            self.core
        ).map_success_to_awaitable_result(f)

    def map_to_result(
        self, f: Callable[[_T_co], Result[_F, _S]]
    ) -> AwaitableResultWrapper[_F, _S]:
        """Apply a synchronous function with return type [trcks.Result][]
        to the wrapped [collections.abc.Awaitable][] object.

        Args:
            f: The synchronous function to be applied.

        Returns:
            A [trcks.oop.AwaitableResultWrapper][] instance with
                the result of the function application.

        Example:
            >>> import asyncio
            >>> from trcks.oop import AwaitableWrapper
            >>> awaitable_result_wrapper = (
            ...     AwaitableWrapper
            ...     .construct(-1)
            ...     .map_to_result(
            ...         lambda x: (
            ...             ("success", x) if x >= 0 else ("failure", "negative value")
            ...         )
            ...     )
            ... )
            >>> awaitable_result_wrapper
            AwaitableResultWrapper(core=<coroutine object ...>)
            >>> asyncio.run(awaitable_result_wrapper.core_as_coroutine)
            ('failure', 'negative value')
        """
        return AwaitableResultWrapper.construct_success_from_awaitable(
            self.core
        ).map_success_to_result(f)

    def tap(self, f: Callable[[_T_co], object]) -> AwaitableWrapper[_T_co]:
        """Apply a synchronous side effect
        to the wrapped [collections.abc.Awaitable][] object.

        Args:
            f: The synchronous side effect to be applied.

        Returns:
            A new [trcks.oop.AwaitableWrapper][] instance with
                the original [collections.abc.Awaitable][] object.

        Example:
            >>> import asyncio
            >>> from trcks.oop import AwaitableWrapper
            >>> awaitable_wrapper = AwaitableWrapper.construct("Hello, world!").tap(
            ...     lambda s: print(f"String: {s}")
            ... )
            >>> value = asyncio.run(awaitable_wrapper.core_as_coroutine)
            String: Hello, world!
            >>> value
            'Hello, world!'
        """
        return AwaitableWrapper(a.tap(f)(self.core))

    def tap_to_awaitable(
        self, f: Callable[[_T_co], Awaitable[object]]
    ) -> AwaitableWrapper[_T_co]:
        """Apply an asynchronous side effect
        to the wrapped [collections.abc.Awaitable][] object.

        Args:
            f: The asynchronous side effect to be applied.

        Returns:
            A [trcks.oop.AwaitableWrapper][] instance with the original wrapped object.

        Example:
            >>> import asyncio
            >>> from trcks.oop import AwaitableWrapper
            >>> async def write_to_disk(output: str) -> None:
            ...     await asyncio.sleep(0.001)
            ...     print(f"Wrote '{output}' to disk.")
            ...
            >>> awaitable_wrapper = AwaitableWrapper.construct(
            ...     "Hello, world!"
            ... ).tap_to_awaitable(write_to_disk)
            >>> value = asyncio.run(awaitable_wrapper.core_as_coroutine)
            Wrote 'Hello, world!' to disk.
            >>> value
            'Hello, world!'
        """
        return AwaitableWrapper(a.tap_to_awaitable(f)(self.core))

    def tap_to_awaitable_result(
        self, f: Callable[[_T_co], AwaitableResult[_F, object]]
    ) -> AwaitableResultWrapper[_F, _T_co]:
        """Apply an asynchronous side effect with return type [trcks.Result][]
        to the wrapped object.

        Args:
            f: The asynchronous side effect to be applied.

        Returns:
            A [trcks.oop.AwaitableResultWrapper][] instance with

                - *the returned* [trcks.Failure][]
                    if the given side effect returns a [trcks.Failure][] or
                - a [trcks.Success][] instance containing *the original* wrapped object
                    if the given side effect returns a [trcks.Success][].

        Example:
            >>> import asyncio
            >>> from typing import Literal
            >>> from trcks import Result
            >>> from trcks.oop import AwaitableWrapper
            >>> WriteErrorLiteral = Literal["write error"]
            >>> async def write_to_disk(s: str, path: str) -> Result[
            ...     WriteErrorLiteral, None
            ... ]:
            ...     if path != "output.txt":
            ...         return "failure", "write error"
            ...     await asyncio.sleep(0.001)
            ...     print(f"Wrote '{s}' to file {path}.")
            ...     return "success", None
            ...
            >>> awaitable_wrapper_1 = AwaitableWrapper.construct(
            ...     "Hello, world!"
            ... ).tap_to_awaitable_result(lambda s: write_to_disk(s, "destination.txt"))
            >>> result_1 = asyncio.run(awaitable_wrapper_1.core_as_coroutine)
            >>> result_1
            ('failure', 'write error')
            >>> awaitable_wrapper_2 = AwaitableWrapper.construct(
            ...     "Hello, world!"
            ... ).tap_to_awaitable_result(lambda s: write_to_disk(s, "output.txt"))
            >>> result_2 = asyncio.run(awaitable_wrapper_2.core_as_coroutine)
            Wrote 'Hello, world!' to file output.txt.
            >>> result_2
            ('success', 'Hello, world!')
        """
        return AwaitableResultWrapper.construct_success_from_awaitable(
            self.core
        ).tap_success_to_awaitable_result(f)

    def tap_to_result(
        self, f: Callable[[_T_co], Result[_F, object]]
    ) -> AwaitableResultWrapper[_F, _T_co]:
        """Apply a synchronous side effect with return type [trcks.Result][]
        to the wrapped object.

        Args:
            f: The synchronous side effect to be applied.

        Returns:
            A [trcks.oop.AwaitableResultWrapper][] instance with

                - *the returned* [trcks.Failure][]
                    if the given side effect returns a [trcks.Failure][] or
                - a [trcks.Success][] instance containing *the original* wrapped object
                    if the given side effect returns a [trcks.Success][].

        Example:
            >>> import asyncio
            >>> from trcks import Result
            >>> from trcks.oop import AwaitableWrapper
            >>> def print_positive_float(x: float) -> Result[str, None]:
            ...     if x <= 0:
            ...         return "failure", "not positive"
            ...     return "success", print(f"Positive float: {x}")
            ...
            >>>
            >>> awaitable_result_wrapper_1 = AwaitableWrapper.construct(
            ...     -2.3
            ... ).tap_to_result(print_positive_float)
            >>> result_1 = asyncio.run(awaitable_result_wrapper_1.core_as_coroutine)
            >>> result_1
            ('failure', 'not positive')
            >>> awaitable_result_wrapper_2 = AwaitableWrapper.construct(
            ...     3.5
            ... ).tap_to_result(print_positive_float)
            >>> result_2 = asyncio.run(awaitable_result_wrapper_2.core_as_coroutine)
            Positive float: 3.5
            >>> result_2
            ('success', 3.5)
        """
        return AwaitableResultWrapper.construct_success_from_awaitable(
            self.core
        ).tap_success_to_result(f)

construct(value) staticmethod

Construct and wrap an collections.abc.Awaitable object from a value.

Parameters:

  • value (_T) –

    The value to be wrapped.

Returns:

Example 
>>> import asyncio
>>> from trcks.oop import AwaitableWrapper
>>> awaitable_wrapper = AwaitableWrapper.construct("Hello, world!")
>>> awaitable_wrapper
AwaitableWrapper(core=<coroutine object ...>)
>>> asyncio.run(awaitable_wrapper.core_as_coroutine)
'Hello, world!'
Source code in src/trcks/oop.py 
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
@staticmethod
def construct(value: _T) -> AwaitableWrapper[_T]:
    """Construct and wrap an [collections.abc.Awaitable][] object from a value.

    Args:
        value: The value to be wrapped.

    Returns:
        A new [trcks.oop.AwaitableWrapper][] instance
            with the wrapped [collections.abc.Awaitable][] object.

    Example:
        >>> import asyncio
        >>> from trcks.oop import AwaitableWrapper
        >>> awaitable_wrapper = AwaitableWrapper.construct("Hello, world!")
        >>> awaitable_wrapper
        AwaitableWrapper(core=<coroutine object ...>)
        >>> asyncio.run(awaitable_wrapper.core_as_coroutine)
        'Hello, world!'
    """
    return AwaitableWrapper(a.construct(value))

construct_from_awaitable(awtbl) staticmethod

Alias for the default constructor.

Parameters:

Returns:

Example 
>>> import asyncio
>>> from trcks.oop import AwaitableWrapper
>>> async def read_from_disk() -> str:
...     return await asyncio.sleep(0.001, result="Hello, world!")
...
>>> awaitable_str = read_from_disk()
>>> awaitable_wrapper = AwaitableWrapper.construct_from_awaitable(
...     awaitable_str
... )
>>> awaitable_wrapper
AwaitableWrapper(core=<coroutine object read_from_disk at 0x...>)
>>> asyncio.run(awaitable_wrapper.core_as_coroutine)
'Hello, world!'
Source code in src/trcks/oop.py 
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
@staticmethod
def construct_from_awaitable(awtbl: Awaitable[_T]) -> AwaitableWrapper[_T]:
    """Alias for the default constructor.

    Args:
        awtbl: The [collections.abc.Awaitable][] to be wrapped.

    Returns:
        A new [trcks.oop.AwaitableWrapper][] instance
            with the wrapped [collections.abc.Awaitable][] object.

    Example:
        >>> import asyncio
        >>> from trcks.oop import AwaitableWrapper
        >>> async def read_from_disk() -> str:
        ...     return await asyncio.sleep(0.001, result="Hello, world!")
        ...
        >>> awaitable_str = read_from_disk()
        >>> awaitable_wrapper = AwaitableWrapper.construct_from_awaitable(
        ...     awaitable_str
        ... )
        >>> awaitable_wrapper
        AwaitableWrapper(core=<coroutine object read_from_disk at 0x...>)
        >>> asyncio.run(awaitable_wrapper.core_as_coroutine)
        'Hello, world!'
    """
    return AwaitableWrapper(awtbl)

map(f)

Apply a synchronous function to the wrapped collections.abc.Awaitable object.

Parameters:

  • f (Callable[[_T_co], _T]) –

    The synchronous function to be applied.

Returns:

Example 
>>> import asyncio
>>> from trcks.oop import AwaitableWrapper
>>> def transform(s: str) -> str:
...     return f"Length: {len(s)}"
...
>>> awaitable_wrapper = (
...     AwaitableWrapper
...     .construct("Hello, world!")
...     .map(transform)
... )
>>> awaitable_wrapper
AwaitableWrapper(core=<coroutine object ...>)
>>> asyncio.run(awaitable_wrapper.core_as_coroutine)
'Length: 13'
Source code in src/trcks/oop.py 
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
def map(self, f: Callable[[_T_co], _T]) -> AwaitableWrapper[_T]:
    """Apply a synchronous function
    to the wrapped [collections.abc.Awaitable][] object.

    Args:
        f: The synchronous function to be applied.

    Returns:
        A new [trcks.oop.AwaitableWrapper][] instance with
            the result of the function application.

    Example:
        >>> import asyncio
        >>> from trcks.oop import AwaitableWrapper
        >>> def transform(s: str) -> str:
        ...     return f"Length: {len(s)}"
        ...
        >>> awaitable_wrapper = (
        ...     AwaitableWrapper
        ...     .construct("Hello, world!")
        ...     .map(transform)
        ... )
        >>> awaitable_wrapper
        AwaitableWrapper(core=<coroutine object ...>)
        >>> asyncio.run(awaitable_wrapper.core_as_coroutine)
        'Length: 13'
    """
    return AwaitableWrapper(a.map_(f)(self.core))

map_to_awaitable(f)

Apply an asynchronous function to the wrapped collections.abc.Awaitable object.

Parameters:

Returns:

Example 
>>> import asyncio
>>> from trcks.oop import AwaitableWrapper
>>> async def write_to_disk(output: str) -> None:
...     await asyncio.sleep(0.001)
...     print(f"Wrote '{output}' to disk.")
...
>>> awaitable_wrapper = (
...     AwaitableWrapper
...     .construct("Hello, world!")
...     .map_to_awaitable(write_to_disk)
... )
>>> awaitable_wrapper
AwaitableWrapper(core=<coroutine object ...>)
>>> asyncio.run(awaitable_wrapper.core_as_coroutine)
Wrote 'Hello, world!' to disk.
Source code in src/trcks/oop.py 
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
def map_to_awaitable(
    self, f: Callable[[_T_co], Awaitable[_T]]
) -> AwaitableWrapper[_T]:
    """Apply an asynchronous function
    to the wrapped [collections.abc.Awaitable][] object.

    Args:
        f: The asynchronous function to be applied.

    Returns:
        A new [trcks.oop.AwaitableWrapper][] instance with
            the result of the function application.

    Example:
        >>> import asyncio
        >>> from trcks.oop import AwaitableWrapper
        >>> async def write_to_disk(output: str) -> None:
        ...     await asyncio.sleep(0.001)
        ...     print(f"Wrote '{output}' to disk.")
        ...
        >>> awaitable_wrapper = (
        ...     AwaitableWrapper
        ...     .construct("Hello, world!")
        ...     .map_to_awaitable(write_to_disk)
        ... )
        >>> awaitable_wrapper
        AwaitableWrapper(core=<coroutine object ...>)
        >>> asyncio.run(awaitable_wrapper.core_as_coroutine)
        Wrote 'Hello, world!' to disk.
    """
    return AwaitableWrapper(a.map_to_awaitable(f)(self.core))

map_to_awaitable_result(f)

Apply an asynchronous function with return type trcks.Result to the wrapped collections.abc.Awaitable object.

Parameters:

Returns:

Example 
>>> import asyncio
>>> from trcks import Result
>>> from trcks.oop import AwaitableWrapper
>>> async def slowly_assert_non_negative(
...     x: float,
... ) -> Result[str, float]:
...     await asyncio.sleep(0.001)
...     if x < 0:
...         return "failure", "negative value"
...     return "success", x
...
>>> awaitable_result_wrapper = (
...     AwaitableWrapper
...     .construct(42.0)
...     .map_to_awaitable_result(slowly_assert_non_negative)
... )
>>> awaitable_result_wrapper
AwaitableResultWrapper(core=<coroutine object ...>)
>>> asyncio.run(awaitable_result_wrapper.core_as_coroutine)
('success', 42.0)
Source code in src/trcks/oop.py 
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
def map_to_awaitable_result(
    self, f: Callable[[_T_co], AwaitableResult[_F, _S]]
) -> AwaitableResultWrapper[_F, _S]:
    """Apply an asynchronous function with return type [trcks.Result][]
    to the wrapped [collections.abc.Awaitable][] object.

    Args:
        f: The asynchronous function to be applied.

    Returns:
        A [trcks.oop.AwaitableResultWrapper][] instance with
            the result of the function application.

    Example:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.oop import AwaitableWrapper
        >>> async def slowly_assert_non_negative(
        ...     x: float,
        ... ) -> Result[str, float]:
        ...     await asyncio.sleep(0.001)
        ...     if x < 0:
        ...         return "failure", "negative value"
        ...     return "success", x
        ...
        >>> awaitable_result_wrapper = (
        ...     AwaitableWrapper
        ...     .construct(42.0)
        ...     .map_to_awaitable_result(slowly_assert_non_negative)
        ... )
        >>> awaitable_result_wrapper
        AwaitableResultWrapper(core=<coroutine object ...>)
        >>> asyncio.run(awaitable_result_wrapper.core_as_coroutine)
        ('success', 42.0)
    """
    return AwaitableResultWrapper.construct_success_from_awaitable(
        self.core
    ).map_success_to_awaitable_result(f)

map_to_result(f)

Apply a synchronous function with return type trcks.Result to the wrapped collections.abc.Awaitable object.

Parameters:

  • f (Callable[[_T_co], Result[_F, _S]]) –

    The synchronous function to be applied.

Returns:

Example 
>>> import asyncio
>>> from trcks.oop import AwaitableWrapper
>>> awaitable_result_wrapper = (
...     AwaitableWrapper
...     .construct(-1)
...     .map_to_result(
...         lambda x: (
...             ("success", x) if x >= 0 else ("failure", "negative value")
...         )
...     )
... )
>>> awaitable_result_wrapper
AwaitableResultWrapper(core=<coroutine object ...>)
>>> asyncio.run(awaitable_result_wrapper.core_as_coroutine)
('failure', 'negative value')
Source code in src/trcks/oop.py 
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
def map_to_result(
    self, f: Callable[[_T_co], Result[_F, _S]]
) -> AwaitableResultWrapper[_F, _S]:
    """Apply a synchronous function with return type [trcks.Result][]
    to the wrapped [collections.abc.Awaitable][] object.

    Args:
        f: The synchronous function to be applied.

    Returns:
        A [trcks.oop.AwaitableResultWrapper][] instance with
            the result of the function application.

    Example:
        >>> import asyncio
        >>> from trcks.oop import AwaitableWrapper
        >>> awaitable_result_wrapper = (
        ...     AwaitableWrapper
        ...     .construct(-1)
        ...     .map_to_result(
        ...         lambda x: (
        ...             ("success", x) if x >= 0 else ("failure", "negative value")
        ...         )
        ...     )
        ... )
        >>> awaitable_result_wrapper
        AwaitableResultWrapper(core=<coroutine object ...>)
        >>> asyncio.run(awaitable_result_wrapper.core_as_coroutine)
        ('failure', 'negative value')
    """
    return AwaitableResultWrapper.construct_success_from_awaitable(
        self.core
    ).map_success_to_result(f)

tap(f)

Apply a synchronous side effect to the wrapped collections.abc.Awaitable object.

Parameters:

  • f (Callable[[_T_co], object]) –

    The synchronous side effect to be applied.

Returns:

Example 
>>> import asyncio
>>> from trcks.oop import AwaitableWrapper
>>> awaitable_wrapper = AwaitableWrapper.construct("Hello, world!").tap(
...     lambda s: print(f"String: {s}")
... )
>>> value = asyncio.run(awaitable_wrapper.core_as_coroutine)
String: Hello, world!
>>> value
'Hello, world!'
Source code in src/trcks/oop.py 
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
def tap(self, f: Callable[[_T_co], object]) -> AwaitableWrapper[_T_co]:
    """Apply a synchronous side effect
    to the wrapped [collections.abc.Awaitable][] object.

    Args:
        f: The synchronous side effect to be applied.

    Returns:
        A new [trcks.oop.AwaitableWrapper][] instance with
            the original [collections.abc.Awaitable][] object.

    Example:
        >>> import asyncio
        >>> from trcks.oop import AwaitableWrapper
        >>> awaitable_wrapper = AwaitableWrapper.construct("Hello, world!").tap(
        ...     lambda s: print(f"String: {s}")
        ... )
        >>> value = asyncio.run(awaitable_wrapper.core_as_coroutine)
        String: Hello, world!
        >>> value
        'Hello, world!'
    """
    return AwaitableWrapper(a.tap(f)(self.core))

tap_to_awaitable(f)

Apply an asynchronous side effect to the wrapped collections.abc.Awaitable object.

Parameters:

Returns:

Example 
>>> import asyncio
>>> from trcks.oop import AwaitableWrapper
>>> async def write_to_disk(output: str) -> None:
...     await asyncio.sleep(0.001)
...     print(f"Wrote '{output}' to disk.")
...
>>> awaitable_wrapper = AwaitableWrapper.construct(
...     "Hello, world!"
... ).tap_to_awaitable(write_to_disk)
>>> value = asyncio.run(awaitable_wrapper.core_as_coroutine)
Wrote 'Hello, world!' to disk.
>>> value
'Hello, world!'
Source code in src/trcks/oop.py 
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
def tap_to_awaitable(
    self, f: Callable[[_T_co], Awaitable[object]]
) -> AwaitableWrapper[_T_co]:
    """Apply an asynchronous side effect
    to the wrapped [collections.abc.Awaitable][] object.

    Args:
        f: The asynchronous side effect to be applied.

    Returns:
        A [trcks.oop.AwaitableWrapper][] instance with the original wrapped object.

    Example:
        >>> import asyncio
        >>> from trcks.oop import AwaitableWrapper
        >>> async def write_to_disk(output: str) -> None:
        ...     await asyncio.sleep(0.001)
        ...     print(f"Wrote '{output}' to disk.")
        ...
        >>> awaitable_wrapper = AwaitableWrapper.construct(
        ...     "Hello, world!"
        ... ).tap_to_awaitable(write_to_disk)
        >>> value = asyncio.run(awaitable_wrapper.core_as_coroutine)
        Wrote 'Hello, world!' to disk.
        >>> value
        'Hello, world!'
    """
    return AwaitableWrapper(a.tap_to_awaitable(f)(self.core))

tap_to_awaitable_result(f)

Apply an asynchronous side effect with return type trcks.Result to the wrapped object.

Parameters:

Returns:

Example 
>>> import asyncio
>>> from typing import Literal
>>> from trcks import Result
>>> from trcks.oop import AwaitableWrapper
>>> WriteErrorLiteral = Literal["write error"]
>>> async def write_to_disk(s: str, path: str) -> Result[
...     WriteErrorLiteral, None
... ]:
...     if path != "output.txt":
...         return "failure", "write error"
...     await asyncio.sleep(0.001)
...     print(f"Wrote '{s}' to file {path}.")
...     return "success", None
...
>>> awaitable_wrapper_1 = AwaitableWrapper.construct(
...     "Hello, world!"
... ).tap_to_awaitable_result(lambda s: write_to_disk(s, "destination.txt"))
>>> result_1 = asyncio.run(awaitable_wrapper_1.core_as_coroutine)
>>> result_1
('failure', 'write error')
>>> awaitable_wrapper_2 = AwaitableWrapper.construct(
...     "Hello, world!"
... ).tap_to_awaitable_result(lambda s: write_to_disk(s, "output.txt"))
>>> result_2 = asyncio.run(awaitable_wrapper_2.core_as_coroutine)
Wrote 'Hello, world!' to file output.txt.
>>> result_2
('success', 'Hello, world!')
Source code in src/trcks/oop.py 
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
def tap_to_awaitable_result(
    self, f: Callable[[_T_co], AwaitableResult[_F, object]]
) -> AwaitableResultWrapper[_F, _T_co]:
    """Apply an asynchronous side effect with return type [trcks.Result][]
    to the wrapped object.

    Args:
        f: The asynchronous side effect to be applied.

    Returns:
        A [trcks.oop.AwaitableResultWrapper][] instance with

            - *the returned* [trcks.Failure][]
                if the given side effect returns a [trcks.Failure][] or
            - a [trcks.Success][] instance containing *the original* wrapped object
                if the given side effect returns a [trcks.Success][].

    Example:
        >>> import asyncio
        >>> from typing import Literal
        >>> from trcks import Result
        >>> from trcks.oop import AwaitableWrapper
        >>> WriteErrorLiteral = Literal["write error"]
        >>> async def write_to_disk(s: str, path: str) -> Result[
        ...     WriteErrorLiteral, None
        ... ]:
        ...     if path != "output.txt":
        ...         return "failure", "write error"
        ...     await asyncio.sleep(0.001)
        ...     print(f"Wrote '{s}' to file {path}.")
        ...     return "success", None
        ...
        >>> awaitable_wrapper_1 = AwaitableWrapper.construct(
        ...     "Hello, world!"
        ... ).tap_to_awaitable_result(lambda s: write_to_disk(s, "destination.txt"))
        >>> result_1 = asyncio.run(awaitable_wrapper_1.core_as_coroutine)
        >>> result_1
        ('failure', 'write error')
        >>> awaitable_wrapper_2 = AwaitableWrapper.construct(
        ...     "Hello, world!"
        ... ).tap_to_awaitable_result(lambda s: write_to_disk(s, "output.txt"))
        >>> result_2 = asyncio.run(awaitable_wrapper_2.core_as_coroutine)
        Wrote 'Hello, world!' to file output.txt.
        >>> result_2
        ('success', 'Hello, world!')
    """
    return AwaitableResultWrapper.construct_success_from_awaitable(
        self.core
    ).tap_success_to_awaitable_result(f)

tap_to_result(f)

Apply a synchronous side effect with return type trcks.Result to the wrapped object.

Parameters:

Returns:

Example 
>>> import asyncio
>>> from trcks import Result
>>> from trcks.oop import AwaitableWrapper
>>> def print_positive_float(x: float) -> Result[str, None]:
...     if x <= 0:
...         return "failure", "not positive"
...     return "success", print(f"Positive float: {x}")
...
>>>
>>> awaitable_result_wrapper_1 = AwaitableWrapper.construct(
...     -2.3
... ).tap_to_result(print_positive_float)
>>> result_1 = asyncio.run(awaitable_result_wrapper_1.core_as_coroutine)
>>> result_1
('failure', 'not positive')
>>> awaitable_result_wrapper_2 = AwaitableWrapper.construct(
...     3.5
... ).tap_to_result(print_positive_float)
>>> result_2 = asyncio.run(awaitable_result_wrapper_2.core_as_coroutine)
Positive float: 3.5
>>> result_2
('success', 3.5)
Source code in src/trcks/oop.py 
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
def tap_to_result(
    self, f: Callable[[_T_co], Result[_F, object]]
) -> AwaitableResultWrapper[_F, _T_co]:
    """Apply a synchronous side effect with return type [trcks.Result][]
    to the wrapped object.

    Args:
        f: The synchronous side effect to be applied.

    Returns:
        A [trcks.oop.AwaitableResultWrapper][] instance with

            - *the returned* [trcks.Failure][]
                if the given side effect returns a [trcks.Failure][] or
            - a [trcks.Success][] instance containing *the original* wrapped object
                if the given side effect returns a [trcks.Success][].

    Example:
        >>> import asyncio
        >>> from trcks import Result
        >>> from trcks.oop import AwaitableWrapper
        >>> def print_positive_float(x: float) -> Result[str, None]:
        ...     if x <= 0:
        ...         return "failure", "not positive"
        ...     return "success", print(f"Positive float: {x}")
        ...
        >>>
        >>> awaitable_result_wrapper_1 = AwaitableWrapper.construct(
        ...     -2.3
        ... ).tap_to_result(print_positive_float)
        >>> result_1 = asyncio.run(awaitable_result_wrapper_1.core_as_coroutine)
        >>> result_1
        ('failure', 'not positive')
        >>> awaitable_result_wrapper_2 = AwaitableWrapper.construct(
        ...     3.5
        ... ).tap_to_result(print_positive_float)
        >>> result_2 = asyncio.run(awaitable_result_wrapper_2.core_as_coroutine)
        Positive float: 3.5
        >>> result_2
        ('success', 3.5)
    """
    return AwaitableResultWrapper.construct_success_from_awaitable(
        self.core
    ).tap_success_to_result(f)