potiklib 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
potiklib/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ from potiklib._main import apotik, potik, run, task
2
+
3
+ __all__ = ["apotik", "potik", "run", "task"]
potiklib/_main.py ADDED
@@ -0,0 +1,236 @@
1
+ import asyncio
2
+ import functools
3
+ import inspect
4
+ import os
5
+ import sys
6
+ import threading
7
+ from collections.abc import Awaitable, Callable, Coroutine
8
+ from contextvars import ContextVar
9
+ from typing import Any, overload
10
+
11
+ from potiklib.providers.atpe import ATPEProvider
12
+ from potiklib.providers.base import SyncProvider
13
+ from potiklib.providers.ipe import IPEProvider
14
+ from potiklib.providers.tpe import TPEProvider
15
+
16
+
17
+ class _Runtime:
18
+ """Manages lazy provider creation and graceful shutdown for a potiklib.run() session."""
19
+
20
+ def __init__(self, workers: int) -> None:
21
+ self.workers = workers
22
+ self._lock = threading.Lock()
23
+ self._closing = False
24
+ self._atpe: ATPEProvider | None = None
25
+ self._tpe: TPEProvider | None = None
26
+ self._ipe: IPEProvider | None = None
27
+
28
+ def get_atpe(self) -> ATPEProvider:
29
+ with self._lock:
30
+ if self._closing:
31
+ raise RuntimeError("potiklib runtime is shutting down")
32
+ if self._atpe is None:
33
+ self._atpe = ATPEProvider(self.workers)
34
+ return self._atpe
35
+
36
+ def get_tpe(self) -> TPEProvider:
37
+ with self._lock:
38
+ if self._closing:
39
+ raise RuntimeError("potiklib runtime is shutting down")
40
+ if self._tpe is None:
41
+ self._tpe = TPEProvider(self.workers)
42
+ return self._tpe
43
+
44
+ def get_ipe(self) -> IPEProvider:
45
+ with self._lock:
46
+ if self._closing:
47
+ raise RuntimeError("potiklib runtime is shutting down")
48
+ if self._ipe is None:
49
+ self._ipe = IPEProvider(self.workers)
50
+ return self._ipe
51
+
52
+ def get_sync_provider(self) -> SyncProvider:
53
+ if sys._is_gil_enabled():
54
+ return self.get_ipe()
55
+ return self.get_tpe()
56
+
57
+ def shutdown(self) -> None:
58
+ with self._lock:
59
+ atpe = self._atpe
60
+
61
+ first_exc: BaseException | None = None
62
+ if atpe is not None:
63
+ try:
64
+ atpe.shutdown(wait=True)
65
+ except BaseException as exc:
66
+ first_exc = exc
67
+
68
+ with self._lock:
69
+ self._closing = True
70
+ tpe = self._tpe
71
+ ipe = self._ipe
72
+
73
+ for provider in (tpe, ipe):
74
+ if provider is not None:
75
+ try:
76
+ provider.shutdown(wait=True)
77
+ except BaseException as exc:
78
+ if first_exc is None:
79
+ first_exc = exc
80
+
81
+ if first_exc is not None:
82
+ raise first_exc
83
+
84
+
85
+ _runtime_var: ContextVar[_Runtime | None] = ContextVar("potiklib_runtime", default=None)
86
+ _global_runtime: _Runtime | None = None
87
+
88
+
89
+ def _get_runtime() -> _Runtime | None:
90
+ runtime = _runtime_var.get()
91
+ if runtime is not None:
92
+ return runtime
93
+ return _global_runtime
94
+
95
+
96
+ @overload
97
+ def run[R](main: Awaitable[R], *, workers: int | None = None) -> R: ...
98
+
99
+
100
+ @overload
101
+ def run[R](main: Callable[[], Awaitable[R]], *, workers: int | None = None) -> R: ...
102
+
103
+
104
+ @overload
105
+ def run[R](main: Callable[[], R], *, workers: int | None = None) -> R: ...
106
+
107
+
108
+ def run[R](
109
+ main: Awaitable[R] | Callable[[], Any],
110
+ *,
111
+ workers: int | None = None,
112
+ ) -> Any:
113
+ """Run main function or coroutine inside a potiklib runtime."""
114
+ global _global_runtime
115
+
116
+ resolved_workers = (os.process_cpu_count() or 1) if workers is None else workers
117
+ if resolved_workers < 1:
118
+ if inspect.iscoroutine(main):
119
+ main.close()
120
+ raise ValueError("workers must be >= 1")
121
+
122
+ if not (inspect.isawaitable(main) or callable(main)):
123
+ raise TypeError(f"run() expected a callable or coroutine, got {type(main).__name__}")
124
+
125
+ runtime = _Runtime(resolved_workers)
126
+ prev_global = _global_runtime
127
+ _global_runtime = runtime
128
+ token = _runtime_var.set(runtime)
129
+ try:
130
+ if inspect.iscoroutine(main):
131
+ return asyncio.run(main)
132
+ if inspect.iscoroutinefunction(main):
133
+ return asyncio.run(main())
134
+ if inspect.isawaitable(main):
135
+
136
+ async def _await_main() -> Any:
137
+ return await main
138
+
139
+ return asyncio.run(_await_main())
140
+ if callable(main):
141
+ return main()
142
+ raise TypeError(f"run() expected a callable or coroutine, got {type(main).__name__}")
143
+ finally:
144
+ _runtime_var.reset(token)
145
+ _global_runtime = prev_global
146
+ runtime.shutdown()
147
+
148
+
149
+ def potik[**P, R](fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> R:
150
+ """Execute a synchronous callable in the sync worker pool, or locally outside run()."""
151
+ if getattr(fn, "_potik_task", False):
152
+ fn = getattr(fn, "__wrapped__", fn)
153
+
154
+ runtime = _get_runtime()
155
+ if runtime is None:
156
+ return fn(*args, **kwargs)
157
+ return runtime.get_sync_provider().execute(fn, *args, **kwargs)
158
+
159
+
160
+ @overload
161
+ async def apotik[R](target: Awaitable[R], /) -> R: ...
162
+
163
+
164
+ @overload
165
+ async def apotik[**P, R](
166
+ target: Callable[P, Awaitable[R]], /, *args: P.args, **kwargs: P.kwargs
167
+ ) -> R: ...
168
+
169
+
170
+ @overload
171
+ async def apotik[**P, R](target: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> R: ...
172
+
173
+
174
+ async def apotik(target: Any, /, *args: Any, **kwargs: Any) -> Any:
175
+ """Execute an awaitable, async callable, or sync callable asynchronously in worker pools."""
176
+ if inspect.isawaitable(target):
177
+ if args or kwargs:
178
+ raise TypeError("apotik() cannot accept arguments for an already-created Awaitable")
179
+ runtime = _get_runtime()
180
+ if runtime is None:
181
+ return await target
182
+ return await runtime.get_atpe().execute_awaitable(target)
183
+
184
+ if callable(target):
185
+ if getattr(target, "_potik_task", False):
186
+ target = getattr(target, "__wrapped__", target)
187
+
188
+ runtime = _get_runtime()
189
+ if inspect.iscoroutinefunction(target):
190
+ if runtime is None:
191
+ return await target(*args, **kwargs)
192
+ return await runtime.get_atpe().execute_callable(target, *args, **kwargs)
193
+
194
+ if runtime is None:
195
+ result = target(*args, **kwargs)
196
+ if inspect.isawaitable(result):
197
+ return await result
198
+ return result
199
+ return await runtime.get_sync_provider().execute_async(target, *args, **kwargs)
200
+
201
+ raise TypeError(f"apotik() expected an awaitable or callable, got {type(target).__name__}")
202
+
203
+
204
+ @overload
205
+ def task[**P, R](
206
+ fn: Callable[P, Coroutine[Any, Any, R]], /
207
+ ) -> Callable[P, Coroutine[Any, Any, R]]: ...
208
+
209
+
210
+ @overload
211
+ def task[**P, R](fn: Callable[P, R], /) -> Callable[P, R]: ...
212
+
213
+
214
+ def task[**P](fn: Callable[P, Any], /) -> Callable[P, Any]:
215
+ """Decorate a sync or async function to run automatically via potiklib workers inside run()."""
216
+ if inspect.iscoroutinefunction(fn):
217
+
218
+ @functools.wraps(fn)
219
+ async def _async_wrapper(*args: P.args, **kwargs: P.kwargs) -> Any:
220
+ runtime = _get_runtime()
221
+ if runtime is None:
222
+ return await fn(*args, **kwargs)
223
+ return await runtime.get_atpe().execute_callable(fn, *args, **kwargs)
224
+
225
+ setattr(_async_wrapper, "_potik_task", True)
226
+ return _async_wrapper
227
+
228
+ @functools.wraps(fn)
229
+ def _sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> Any:
230
+ runtime = _get_runtime()
231
+ if runtime is None:
232
+ return fn(*args, **kwargs)
233
+ return runtime.get_sync_provider().execute(fn, *args, **kwargs)
234
+
235
+ setattr(_sync_wrapper, "_potik_task", True)
236
+ return _sync_wrapper
@@ -0,0 +1,13 @@
1
+ from potiklib.providers.atpe import ATPEProvider
2
+ from potiklib.providers.base import AsyncProvider, Provider, SyncProvider
3
+ from potiklib.providers.ipe import IPEProvider
4
+ from potiklib.providers.tpe import TPEProvider
5
+
6
+ __all__ = [
7
+ "ATPEProvider",
8
+ "AsyncProvider",
9
+ "IPEProvider",
10
+ "Provider",
11
+ "SyncProvider",
12
+ "TPEProvider",
13
+ ]
@@ -0,0 +1,202 @@
1
+ import asyncio
2
+ import contextvars
3
+ import inspect
4
+ import threading
5
+ from collections.abc import Awaitable, Callable, Coroutine
6
+ from concurrent.futures import Future, ThreadPoolExecutor
7
+ from typing import Any
8
+
9
+
10
+ class _WorkerState:
11
+ def __init__(self, index: int) -> None:
12
+ self.index = index
13
+ self.loop: asyncio.AbstractEventLoop | None = None
14
+ self.in_flight = 0
15
+ self.ready = threading.Event()
16
+
17
+
18
+ class ATPEProvider:
19
+ """Async execution provider backed by a ThreadPoolExecutor of event loops."""
20
+
21
+ def __init__(self, workers: int) -> None:
22
+ if workers < 1:
23
+ raise ValueError("workers must be >= 1")
24
+
25
+ self._max_workers = workers
26
+ self._lock = threading.Lock()
27
+ self._idle_cond = threading.Condition(self._lock)
28
+ self._total_in_flight = 0
29
+ self._closing = False
30
+ self._shutdown_done = False
31
+ self._local = threading.local()
32
+ self._workers = [_WorkerState(i) for i in range(workers)]
33
+ self._executor = ThreadPoolExecutor(
34
+ max_workers=workers,
35
+ thread_name_prefix="potik-atpe",
36
+ )
37
+
38
+ try:
39
+ for worker in self._workers:
40
+ self._executor.submit(self._worker_main, worker)
41
+ for worker in self._workers:
42
+ worker.ready.wait()
43
+ except BaseException:
44
+ self.shutdown(wait=False)
45
+ raise
46
+
47
+ def _worker_main(self, worker: _WorkerState) -> None:
48
+ self._local.in_atpe = True
49
+ self._local.worker_index = worker.index
50
+ loop = asyncio.new_event_loop()
51
+ asyncio.set_event_loop(loop)
52
+ worker.loop = loop
53
+ loop.call_soon(worker.ready.set)
54
+ try:
55
+ loop.run_forever()
56
+ finally:
57
+ try:
58
+ pending = asyncio.all_tasks(loop)
59
+ if pending:
60
+ for task in pending:
61
+ task.cancel()
62
+ loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
63
+ loop.run_until_complete(loop.shutdown_asyncgens())
64
+ finally:
65
+ asyncio.set_event_loop(None)
66
+ loop.close()
67
+ self._local.in_atpe = False
68
+
69
+ def _acquire_worker(self) -> _WorkerState:
70
+ with self._lock:
71
+ if self._closing:
72
+ raise RuntimeError("ATPEProvider is shutting down")
73
+ worker = min(self._workers, key=lambda w: w.in_flight)
74
+ worker.in_flight += 1
75
+ self._total_in_flight += 1
76
+ return worker
77
+
78
+ def _release_worker(self, worker: _WorkerState) -> None:
79
+ with self._lock:
80
+ worker.in_flight -= 1
81
+ self._total_in_flight -= 1
82
+ if self._total_in_flight == 0:
83
+ self._idle_cond.notify_all()
84
+
85
+ async def execute_awaitable[R](self, awaitable: Awaitable[R], /) -> R:
86
+ if getattr(self._local, "in_atpe", False):
87
+ return await awaitable
88
+
89
+ if inspect.iscoroutine(awaitable):
90
+ coro: Coroutine[Any, Any, R] = awaitable
91
+ else:
92
+
93
+ async def _wrap_awaitable() -> R:
94
+ return await awaitable
95
+
96
+ coro = _wrap_awaitable()
97
+
98
+ return await self._dispatch_coro(coro)
99
+
100
+ async def execute_callable[**P, R](
101
+ self,
102
+ fn: Callable[P, Coroutine[Any, Any, R] | Awaitable[R]],
103
+ /,
104
+ *args: P.args,
105
+ **kwargs: P.kwargs,
106
+ ) -> R:
107
+ if getattr(self._local, "in_atpe", False):
108
+ return await fn(*args, **kwargs)
109
+
110
+ async def _invoke() -> R:
111
+ return await fn(*args, **kwargs)
112
+
113
+ return await self._dispatch_coro(_invoke())
114
+
115
+ async def _dispatch_coro[R](self, coro: Coroutine[Any, Any, R]) -> R:
116
+ ctx = contextvars.copy_context()
117
+ worker = self._acquire_worker()
118
+ loop = worker.loop
119
+ if loop is None:
120
+ self._release_worker(worker)
121
+ coro.close()
122
+ raise RuntimeError("Worker event loop is not initialized")
123
+
124
+ worker_loop: asyncio.AbstractEventLoop = loop
125
+ cf_future: Future[R] = Future()
126
+ task_holder: list[asyncio.Task[R] | None] = [None]
127
+
128
+ def _on_task_done(task: asyncio.Task[R]) -> None:
129
+ self._release_worker(worker)
130
+ if task.cancelled():
131
+ cf_future.cancel()
132
+ else:
133
+ exc = task.exception()
134
+ if exc is not None:
135
+ if not cf_future.done():
136
+ cf_future.set_exception(exc)
137
+ else:
138
+ if not cf_future.done():
139
+ cf_future.set_result(task.result())
140
+
141
+ def _create_task_and_link() -> None:
142
+ if cf_future.cancelled():
143
+ coro.close()
144
+ self._release_worker(worker)
145
+ return
146
+ try:
147
+ task = worker_loop.create_task(coro)
148
+ except BaseException as exc:
149
+ coro.close()
150
+ if not cf_future.done():
151
+ cf_future.set_exception(exc)
152
+ self._release_worker(worker)
153
+ return
154
+
155
+ task_holder[0] = task
156
+ task.add_done_callback(_on_task_done)
157
+ if cf_future.cancelled():
158
+ task.cancel()
159
+
160
+ def _cancel_worker_task() -> None:
161
+ task = task_holder[0]
162
+ if task is not None and not task.done():
163
+ task.cancel()
164
+
165
+ def _on_cf_done(fut: Future[R]) -> None:
166
+ if fut.cancelled():
167
+ try:
168
+ worker_loop.call_soon_threadsafe(_cancel_worker_task)
169
+ except RuntimeError:
170
+ pass
171
+
172
+ cf_future.add_done_callback(_on_cf_done)
173
+
174
+ try:
175
+ worker_loop.call_soon_threadsafe(ctx.run, _create_task_and_link)
176
+ except BaseException:
177
+ coro.close()
178
+ self._release_worker(worker)
179
+ raise
180
+
181
+ return await asyncio.wrap_future(cf_future)
182
+
183
+ def shutdown(self, wait: bool = True) -> None:
184
+ with self._lock:
185
+ if self._shutdown_done:
186
+ return
187
+ self._closing = True
188
+ if wait:
189
+ while self._total_in_flight > 0:
190
+ self._idle_cond.wait()
191
+ self._shutdown_done = True
192
+ workers = list(self._workers)
193
+
194
+ for worker in workers:
195
+ loop = worker.loop
196
+ if loop is not None and not loop.is_closed():
197
+ try:
198
+ loop.call_soon_threadsafe(loop.stop)
199
+ except RuntimeError:
200
+ pass
201
+
202
+ self._executor.shutdown(wait=wait)
@@ -0,0 +1,37 @@
1
+ from collections.abc import Awaitable, Callable, Coroutine
2
+ from concurrent.futures import Future
3
+ from typing import Any, Protocol
4
+
5
+
6
+ class Provider(Protocol):
7
+ """Base protocol for execution providers."""
8
+
9
+ def shutdown(self, wait: bool = True) -> None: ...
10
+
11
+
12
+ class SyncProvider(Provider, Protocol):
13
+ """Protocol for synchronous execution providers (TPE / IPE)."""
14
+
15
+ def submit[**P, R](
16
+ self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs
17
+ ) -> Future[R]: ...
18
+
19
+ def execute[**P, R](self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> R: ...
20
+
21
+ async def execute_async[**P, R](
22
+ self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs
23
+ ) -> R: ...
24
+
25
+
26
+ class AsyncProvider(Provider, Protocol):
27
+ """Protocol for asynchronous execution providers (ATPE)."""
28
+
29
+ async def execute_awaitable[R](self, awaitable: Awaitable[R], /) -> R: ...
30
+
31
+ async def execute_callable[**P, R](
32
+ self,
33
+ fn: Callable[P, Coroutine[Any, Any, R] | Awaitable[R]],
34
+ /,
35
+ *args: P.args,
36
+ **kwargs: P.kwargs,
37
+ ) -> R: ...
@@ -0,0 +1,40 @@
1
+ import asyncio
2
+ import threading
3
+ from collections.abc import Callable
4
+ from concurrent.futures import Future, InterpreterPoolExecutor
5
+
6
+
7
+ class IPEProvider:
8
+ """Synchronous execution provider backed by InterpreterPoolExecutor."""
9
+
10
+ def __init__(self, workers: int) -> None:
11
+ if workers < 1:
12
+ raise ValueError("workers must be >= 1")
13
+
14
+ self._lock = threading.Lock()
15
+ self._closing = False
16
+ self._executor = InterpreterPoolExecutor(max_workers=workers)
17
+
18
+ def submit[**P, R](self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> Future[R]:
19
+ with self._lock:
20
+ if self._closing:
21
+ raise RuntimeError("IPEProvider is shutting down")
22
+
23
+ target: Callable[P, R] = (
24
+ getattr(fn, "__wrapped__", fn) if getattr(fn, "_potik_task", False) else fn
25
+ )
26
+ return self._executor.submit(target, *args, **kwargs)
27
+
28
+ def execute[**P, R](self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> R:
29
+ return self.submit(fn, *args, **kwargs).result()
30
+
31
+ async def execute_async[**P, R](
32
+ self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs
33
+ ) -> R:
34
+ future = self.submit(fn, *args, **kwargs)
35
+ return await asyncio.wrap_future(future)
36
+
37
+ def shutdown(self, wait: bool = True) -> None:
38
+ with self._lock:
39
+ self._closing = True
40
+ self._executor.shutdown(wait=wait)
@@ -0,0 +1,113 @@
1
+ import asyncio
2
+ import contextvars
3
+ import threading
4
+ from collections.abc import Callable
5
+ from concurrent.futures import Future, ThreadPoolExecutor
6
+ from typing import Any
7
+
8
+
9
+ class TPEProvider:
10
+ """Synchronous execution provider backed by ThreadPoolExecutor."""
11
+
12
+ def __init__(self, workers: int) -> None:
13
+ if workers < 1:
14
+ raise ValueError("workers must be >= 1")
15
+
16
+ self._max_workers = workers
17
+ self._lock = threading.Lock()
18
+ self._active_tasks = 0
19
+ self._closing = False
20
+ self._local = threading.local()
21
+ self._executor = ThreadPoolExecutor(
22
+ max_workers=workers,
23
+ thread_name_prefix="potik-tpe",
24
+ )
25
+
26
+ def _run_in_worker[R](
27
+ self,
28
+ ctx: contextvars.Context,
29
+ fn: Callable[..., R],
30
+ args: tuple[Any, ...],
31
+ kwargs: dict[str, Any],
32
+ release_once: Callable[[], None],
33
+ ) -> R:
34
+ self._local.in_tpe = True
35
+ try:
36
+ return ctx.run(fn, *args, **kwargs)
37
+ finally:
38
+ self._local.in_tpe = False
39
+ release_once()
40
+
41
+ def _make_release_once(self) -> Callable[[], None]:
42
+ released = False
43
+
44
+ def _release() -> None:
45
+ nonlocal released
46
+ with self._lock:
47
+ if not released:
48
+ released = True
49
+ self._active_tasks -= 1
50
+
51
+ return _release
52
+
53
+ def _should_run_locally_or_acquire(self) -> bool:
54
+ with self._lock:
55
+ if self._closing:
56
+ raise RuntimeError("TPEProvider is shutting down")
57
+ if getattr(self._local, "in_tpe", False) and self._active_tasks >= self._max_workers:
58
+ return True
59
+ self._active_tasks += 1
60
+ return False
61
+
62
+ def _submit_to_executor[**P, R](
63
+ self,
64
+ fn: Callable[P, R],
65
+ args: tuple[Any, ...],
66
+ kwargs: dict[str, Any],
67
+ ) -> Future[R]:
68
+ ctx = contextvars.copy_context()
69
+ release_once = self._make_release_once()
70
+
71
+ def _run() -> R:
72
+ return self._run_in_worker(ctx, fn, args, kwargs, release_once)
73
+
74
+ try:
75
+ future = self._executor.submit(_run)
76
+ except BaseException:
77
+ release_once()
78
+ raise
79
+
80
+ future.add_done_callback(lambda _fut: release_once())
81
+ return future
82
+
83
+ def submit[**P, R](self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> Future[R]:
84
+ if self._should_run_locally_or_acquire():
85
+ local_future: Future[R] = Future()
86
+ try:
87
+ result = fn(*args, **kwargs)
88
+ except BaseException as exc:
89
+ local_future.set_exception(exc)
90
+ else:
91
+ local_future.set_result(result)
92
+ return local_future
93
+
94
+ return self._submit_to_executor(fn, args, kwargs)
95
+
96
+ def execute[**P, R](self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> R:
97
+ if self._should_run_locally_or_acquire():
98
+ return fn(*args, **kwargs)
99
+
100
+ return self._submit_to_executor(fn, args, kwargs).result()
101
+
102
+ async def execute_async[**P, R](
103
+ self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs
104
+ ) -> R:
105
+ if self._should_run_locally_or_acquire():
106
+ return fn(*args, **kwargs)
107
+
108
+ return await asyncio.wrap_future(self._submit_to_executor(fn, args, kwargs))
109
+
110
+ def shutdown(self, wait: bool = True) -> None:
111
+ with self._lock:
112
+ self._closing = True
113
+ self._executor.shutdown(wait=wait)
potiklib/py.typed ADDED
File without changes
@@ -0,0 +1,131 @@
1
+ Metadata-Version: 2.4
2
+ Name: potiklib
3
+ Version: 1.0.0
4
+ Summary: Zero-dependency parallel execution library for free-threaded Python 3.15+ and asyncio
5
+ Author: Qulowg
6
+ Author-email: Qulowg <qulowg@gmail.com>
7
+ License-Expression: MIT
8
+ License-File: LICENSE.txt
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Framework :: AsyncIO
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.15
16
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
17
+ Classifier: Typing :: Typed
18
+ Requires-Dist: pytest ; extra == 'dev'
19
+ Requires-Dist: pytest-asyncio ; extra == 'dev'
20
+ Requires-Dist: ruff ; extra == 'dev'
21
+ Requires-Dist: ty ; extra == 'dev'
22
+ Requires-Python: >=3.15
23
+ Project-URL: Homepage, https://github.com/BRamil0/potiklib
24
+ Project-URL: Issues, https://github.com/BRamil0/potiklib/issues
25
+ Provides-Extra: dev
26
+ Description-Content-Type: text/markdown
27
+
28
+ # potiklib
29
+ [Українська версія (README.uk.md)](https://github.com/BRamil0/potiklib/blob/master/README.uk.md)
30
+
31
+ **potiklib** is a zero-dependency Python 3.15+ library that gives you a clean, transparent developer experience for parallel CPU and `asyncio` execution on both free-threaded (`No GIL`) and GIL-enabled Python builds.
32
+ ## Installation
33
+ ```bash
34
+ uv add potiklib
35
+
36
+ uv pip install potiklib
37
+ ```
38
+ ## Quick Start
39
+ ```python
40
+ import asyncio
41
+ from potiklib import apotik, potik, run, task
42
+
43
+
44
+ @task
45
+ def cpu_square(x: int) -> int:
46
+ return x * x
47
+
48
+
49
+ def cpu_cube(x: int) -> int:
50
+ return x * x * x
51
+
52
+
53
+ async def main() -> None:
54
+ squares = await asyncio.gather(*(apotik(cpu_square, i) for i in range(4)))
55
+ cubes = potik(cpu_cube, 3)
56
+ print("squares:", squares, "cube(3):", cubes)
57
+
58
+
59
+ if __name__ == "__main__":
60
+ run(main)
61
+ ```
62
+ ## Usage Examples
63
+ ### Parallel `async def` Tasks (`@task` + `asyncio.gather`)
64
+ ```python
65
+ import asyncio
66
+ from potiklib import run, task
67
+
68
+
69
+ @task
70
+ async def async_cpu_work(n: int) -> int:
71
+ await asyncio.sleep(0)
72
+ total = 0
73
+ for i in range(n):
74
+ total = (total + i * i) % 1_000_000_007
75
+ return total
76
+
77
+
78
+ async def main() -> list[int]:
79
+ return await asyncio.gather(*(async_cpu_work(2_000_000) for _ in range(4)))
80
+
81
+
82
+ if __name__ == "__main__":
83
+ print(run(main, workers=4))
84
+ ```
85
+ ### Synchronous `def` Functions (`potik` & `apotik`)
86
+ ```python
87
+ import asyncio
88
+ from potiklib import apotik, potik, run
89
+
90
+
91
+ def compute_sum(limit: int) -> int:
92
+ total = 0
93
+ for i in range(limit):
94
+ total += i
95
+ return total
96
+
97
+
98
+ def sync_entry() -> int:
99
+ return potik(compute_sum, 1_000_000)
100
+
101
+
102
+ async def async_entry() -> list[int]:
103
+ return await asyncio.gather(
104
+ apotik(compute_sum, 1_000_000),
105
+ apotik(compute_sum, 2_000_000),
106
+ )
107
+
108
+
109
+ if __name__ == "__main__":
110
+ print("sync:", run(sync_entry, workers=2))
111
+ print("async:", run(async_entry, workers=2))
112
+ ```
113
+ ## API Reference
114
+ | Symbol | Inside `run()` | Outside `run()` (fallback) |
115
+ | :--- | :--- | :--- |
116
+ | `run(main, *, workers=None)` | Starts the runtime (`workers` defaults to `os.process_cpu_count() or 1`), runs `def`, `async def`, coroutine, or `Awaitable`, and shuts down initialized pools in `finally`. | — |
117
+ | `@task` on `async def` | Runs in a worker thread's event loop (`ATPE`) with `Least-Loaded` balancing and `contextvars` propagation. | Awaits `fn(*args, **kwargs)` in the caller's event loop. |
118
+ | `@task` on `def` | Runs in `TPE` (No GIL) or `IPE` (GIL) and returns the result. | Calls `fn(*args, **kwargs)` directly. |
119
+ | `potik(fn, /, *args, **kwargs)` | Runs synchronous `fn` in `TPE` or `IPE` and waits for the result (with anti-deadlock fallback when no free threads remain). | Calls `fn(*args, **kwargs)` directly. |
120
+ | `await apotik(target, /, *args, **kwargs)` | Routes `Awaitable` / `async def` to `ATPE`, and synchronous `def` to `TPE` / `IPE`. | Awaits `target` / `target(*args, **kwargs)` or calls synchronous `target` directly. |
121
+
122
+ ## `No GIL` vs `GIL` Routing
123
+ At runtime, `potiklib` checks `sys._is_gil_enabled()` for synchronous tasks and lazily initializes only the pools actually used:
124
+ - **Asynchronous tasks (`async def`, `Awaitable`):** Always routed to `ATPEProvider` (a `ThreadPoolExecutor` where each worker owns an `asyncio` event loop).
125
+ - **Synchronous tasks with No GIL (`sys._is_gil_enabled() == False`):** Routed to `TPEProvider` (`ThreadPoolExecutor` with `contextvars` copying and `Lock`-tracked anti-deadlock detection).
126
+ - **Synchronous tasks with GIL enabled (`sys._is_gil_enabled() == True`):** Routed to `IPEProvider` (`concurrent.futures.InterpreterPoolExecutor`) so CPU-bound work runs in parallel across subinterpreters.
127
+ > **Note:**
128
+ > When the GIL is enabled (`sys._is_gil_enabled() == True`), synchronous functions executed via `InterpreterPoolExecutor` must be picklable / cross-interpreter shareable at module top level: avoid `lambda`, local closures, default arguments that prevent sharing, or module-global references. `@task` preserves `functools.wraps(fn)` so `potiklib` can safely unwrap its own task decorator without stripping your custom decorators.
129
+
130
+ ## License
131
+ MIT License — see [LICENSE.txt](https://github.com/BRamil0/potiklib/blob/master/LICENSE.txt).
@@ -0,0 +1,13 @@
1
+ potiklib/__init__.py,sha256=oGczQA1XWZGKOc1BjYo9fGk0ntHyFuTsC76MjtOPBwg,98
2
+ potiklib/_main.py,sha256=Bq7N19DYPm5thjAuTZaB5tbyB33q4eVgyZDOuuzM6WA,7505
3
+ potiklib/providers/__init__.py,sha256=wW3JtvGV-ah5P11JjaCJjQP7X6DVo5cihNQ0DBZ2Uc4,347
4
+ potiklib/providers/atpe.py,sha256=i6QtLci5rFv6MRaU5NRHLPkrvrS3LkTJZpW4mffwer0,6674
5
+ potiklib/providers/base.py,sha256=_fuNzIp93XvPZZDRI9bxpz6vFkDwHMT8VrrhCtO7gwU,1101
6
+ potiklib/providers/ipe.py,sha256=2F_TAs404BBDnbrvmEcUAuZSZZFjqD7J2v_BGCUeiDM,1437
7
+ potiklib/providers/tpe.py,sha256=0DOKUoG0tw8VB5Y6ZCaRcbB4FTwhmZPzIMSiKoQzDIc,3556
8
+ potiklib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
9
+ potiklib-1.0.0.dist-info/licenses/LICENSE.txt,sha256=cZ01LOL8mNJmKZmgZneUjQP-VNio_o1CJ9n6ER32XuM,1114
10
+ potiklib-1.0.0.dist-info/WHEEL,sha256=3OmCxFA0ffBIsX4x0o8CdfSvZAOvO3mzEG8U_z5TvV4,80
11
+ potiklib-1.0.0.dist-info/entry_points.txt,sha256=1IDGMfJHGUaCv-hLRvxL4GEipnBePVc4Jx81CayGsMY,44
12
+ potiklib-1.0.0.dist-info/METADATA,sha256=B4iSfgs7qVAJ1tcy9bF3BM6XCIQaSRr469usK9XPzYI,5274
13
+ potiklib-1.0.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.13.8
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ potiklib = potiklib:main
3
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright 2026 - now (c) Radomyr B. <qulowg@gmail.com> (https://radomyr.net)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.