Skip to content

Commit

Permalink
Cleanup readme.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@Soheab @mikeshardmind
Soheab authored and mikeshardmind committed Jan 22, 2025
1 parent 47db770 commit 6ddc9f6
Showing 1 changed file with 19 additions and 67 deletions.
86 changes: 19 additions & 67 deletions readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,17 @@
# async-utils

This contains various async utility functions I've written

# Design goals

## The obvious use should be correct
## Design goals

### 1. The obvious use should be correct
Examples of this:

- Any caveats should be documented prominently.
- Internally wrapping user functions should retain features
such as laziness and backpressure (see: gen_transform.py)
- If the library can't correctly wrap behavior, it shouldn't wrap that behavior.

## Pay for only what you use
### 2. Pay for only what you use

This library is designed so that you only pay for the abstractions you use, without
breaking potential interaction with other library uses.
Expand All @@ -26,7 +24,7 @@ This includes:
- Some classes/functions with only minor variations are intentionally duplicated partially.
- possibly more things I'm forgetting right now.

## Task cancellation should only ocur where obvious and documented
### 3. Task cancellation should only ocur where obvious and documented

There's not much further to say about this goal right now, but this
should be expanded on later in the WIP accompanying guide on making
Expand All @@ -39,65 +37,19 @@ prose yet.

What's in each public export, below

## bg_loop.py

Contains a context manager that creates an asyncio event loop in a backgrouns thread and wraps
scheduling to it,

## bg_tasks.py

Contains a lightweight alternative to asyncio TaskGroups, without the entertwined cancellation semantics.

## corofunc_cache.py

Contains lightweight preemptive async caching decorators

## dual_color.py

Note: missing docs

Contains thread-safe queues and a thread-safe semaphore
with both sync and async colored access.

## gen_transform.py

Contains a function to wrap a synchronous generator in a thread use it asynchronously

## lockout.py

async digital loto tags!

## lru.py

A lightweight lru-cache mapping

## priority_sem.py

A priority semaphore.

## ratelimiter.py

A ratelimiting context manager.

## scheduler.py

A simple in-memory asyncio job runner.

## sig_service.py

Note: This needs much better examples and documentation

A means of abstracting signal handling for graceful shutdown
in multi-color concurrent applications

## task_cache.py

Note: This pulls in inspect, see `corofunc_cache.py` for the lightweight
alternative if you don't need direct access to the lower level task objects.

task-based decorators for preemptive async caching.

## waterfall.py
| Module | Description | Notes |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [bg_loop.py](src/async_utils/bg_loop.py) | Contains a context manager that creates an asyncio event loop in a backgrouns thread and wraps scheduling to it, | |
| [bg_tasks.py](src/async_utils/bg_tasks.py) | Contains a lightweight alternative to asyncio TaskGroups, without the entertwined cancellation semantics. | |
| [corofunc_cache.py](src/async_utils/corofunc_cache.py) | Contains lightweight preemptive async caching decorators | |
| [dual_color.py](src/async_utils/dual_color.py) | Contains thread-safe queues and a thread-safe semaphore with both sync and async colored access. | Missing docs |
| [gen_transform.py](src/async_utils/gen_transform.py) | Contains a function to wrap a synchronous generator in a thread use it asynchronously | |
| [lockout.py](src/async_utils/lockout.py) | async digital loto tags! | |
| [lru.py](src/async_utils/lru.py) | A lightweight lru-cache mapping | |
| [priority_sem.py](src/async_utils/priority_sem.py) | A priority semaphore. | |
| [ratelimiter.py](src/async_utils/ratelimiter.py) | A ratelimiting context manager. | |
| [scheduler.py](src/async_utils/scheduler.py) | A simple in-memory asyncio job runner. | |
| [sig_service.py](src/async_utils/sig_service.py) | A means of abstracting signal handling for graceful shutdown in multi-color concurrent applications | Note: This needs much better examples and documentation |
| [task_cache.py](src/async_utils/task_cache.py) | task-based decorators for preemptive async caching. | This pulls in inspect, see [`corofunc_cache.py`](src/async_utils/corofunc_cache.py) for the lightweight if you don't need direct access to the lower level task objects. |
| [waterfall.py](src/async_utils/waterfall.py) | an async batching mechanism that dispatches by volume or time interval, whichever is satisfied first. | |

an async batching mechanism that dispatches by volume or time interval,
whichever is satisfied first.

0 comments on commit 6ddc9f6

Please sign in to comment.