sametime 0.1.0__py3-none-any.whl

sametime/__init__.py

@@ -0,0 +1,215 @@
+"""Bounded synchronous thread concurrency for independent I/O operations."""
+
+from collections.abc import Callable, Iterable, Iterator
+from concurrent.futures import FIRST_COMPLETED, Future, ThreadPoolExecutor, wait
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+import os
+from typing import cast
+
+__version__ = '0.1.0'
+
+__all__ = ['Outcome', 'thread_iter', 'thread_map', 'thread_outcomes', '__version__']
+
+
+@dataclass(frozen=True, slots=True)
+class Outcome[R]:
+    """An indexed result without a separate reference to the input item.
+
+    Returned values and original exceptions may themselves retain input data.
+    Exception tracebacks are preserved; they are not a memory isolation boundary.
+    """
+
+    index: int
+    value: R | None = None
+    error: Exception | None = field(default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        if isinstance(self.index, bool) or not isinstance(self.index, int):
+            raise TypeError('index must be a nonnegative integer')
+        if self.index < 0:
+            raise ValueError('index must be nonnegative')
+        if self.error is not None and not isinstance(self.error, Exception):
+            raise TypeError('error must be an Exception or None')
+        if self.error is not None and self.value is not None:
+            raise ValueError('an outcome cannot contain both a value and an error')
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+    def result(self) -> R:
+        """Return the value (including None), or raise the original exception."""
+        if self.error is not None:
+            raise self.error
+        return cast(R, self.value)
+
+
+def _positive(name: str, value: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f'{name} must be a positive integer')
+    if value <= 0:
+        raise ValueError(f'{name} must be a positive integer')
+    return value
+
+
+def _results[T, R](
+    pool: ThreadPoolExecutor,
+    function: Callable[[T], R],
+    iterable: Iterable[T],
+    max_pending: int,
+    ordered: bool,
+    on_result: Callable[[Outcome[R]], None] | None,
+) -> Iterator[Outcome[R]]:
+    source = iter(iterable)
+    pending: dict[Future[R], int] = {}
+    exhausted = False
+    index = 0
+
+    def fill() -> None:
+        nonlocal exhausted, index
+        while not exhausted and len(pending) < max_pending:
+            try:
+                item = next(source)
+            except StopIteration:
+                exhausted = True
+                break
+            pending[pool.submit(function, item)] = index
+            index += 1
+
+    try:
+        fill()
+        while pending:
+            if ordered:
+                future = next(iter(pending))
+            else:
+                done, _ = wait(pending, return_when=FIRST_COMPLETED)
+                future = min(done, key=pending.__getitem__)
+            result_index = pending.pop(future)
+            try:
+                outcome = Outcome(result_index, value=future.result())
+            except Exception as error:
+                outcome = Outcome(result_index, error=error)
+            if on_result is not None:
+                on_result(outcome)
+            yield outcome
+            fill()
+    finally:
+        for future in pending:
+            future.cancel()
+
+
+@contextmanager
+def _thread_records[T, R](
+    function: Callable[[T], R],
+    iterable: Iterable[T],
+    *,
+    max_workers: int | None = None,
+    max_pending: int | None = None,
+    ordered: bool = True,
+    on_result: Callable[[Outcome[R]], None] | None = None,
+) -> Iterator[Iterator[Outcome[R]]]:
+    if not callable(function):
+        raise TypeError('function must be callable')
+    if not isinstance(ordered, bool):
+        raise TypeError('ordered must be a bool')
+    if on_result is not None and not callable(on_result):
+        raise TypeError('on_result must be callable or None')
+    workers = (
+        min(32, (os.process_cpu_count() or 1) + 4)
+        if max_workers is None
+        else _positive('max_workers', max_workers)
+    )
+    capacity = workers * 2 if max_pending is None else _positive('max_pending', max_pending)
+    pool = ThreadPoolExecutor(max_workers=workers, thread_name_prefix='sametime')
+    results = _results(pool, function, iterable, capacity, ordered, on_result)
+    try:
+        yield results
+    finally:
+        results.close()
+        pool.shutdown(wait=True, cancel_futures=True)
+
+
+@contextmanager
+def thread_iter[T, R](
+    function: Callable[[T], R],
+    iterable: Iterable[T],
+    *,
+    max_workers: int | None = None,
+    max_pending: int | None = None,
+    ordered: bool = True,
+    on_result: Callable[[Outcome[R]], None] | None = None,
+) -> Iterator[Iterator[R]]:
+    """Yield bounded values; always use as a context manager.
+
+    ordered=True preserves input order; false returns ready results first.
+    Worker and input exceptions propagate unchanged. on_result runs on the
+    consuming thread before yielding a value or raising its worker exception.
+    Exit cancels queued calls and joins running calls; I/O needs its own timeout.
+    The caller owns input resources. No input is consumed before iteration.
+    """
+    with _thread_records(
+        function,
+        iterable,
+        max_workers=max_workers,
+        max_pending=max_pending,
+        ordered=ordered,
+        on_result=on_result,
+    ) as records:
+        values = (record.result() for record in records)
+        try:
+            yield values
+        finally:
+            values.close()
+
+
+@contextmanager
+def thread_outcomes[T, R](
+    function: Callable[[T], R],
+    iterable: Iterable[T],
+    *,
+    max_workers: int | None = None,
+    max_pending: int | None = None,
+    ordered: bool = True,
+    on_result: Callable[[Outcome[R]], None] | None = None,
+) -> Iterator[Iterator[Outcome[R]]]:
+    """Yield indexed successes/failures with the same bounds and cleanup.
+
+    Worker Exception instances become outcomes. BaseException, producer failures
+    and callback failures propagate. Only consumed results invoke on_result;
+    unconsumed or cancelled work emits no outcome/callback during context exit.
+    """
+    with _thread_records(
+        function,
+        iterable,
+        max_workers=max_workers,
+        max_pending=max_pending,
+        ordered=ordered,
+        on_result=on_result,
+    ) as records:
+        yield records
+
+
+def thread_map[T, R](
+    function: Callable[[T], R],
+    iterable: Iterable[T],
+    *,
+    max_workers: int | None = None,
+    max_pending: int | None = None,
+    ordered: bool = True,
+    on_result: Callable[[Outcome[R]], None] | None = None,
+) -> list[R]:
+    """Collect thread_iter results into a list; input must terminate.
+
+    Outstanding work is bounded, but the returned list grows with all results.
+    Use thread_iter to process large or infinite inputs incrementally.
+    """
+    with thread_iter(
+        function,
+        iterable,
+        max_workers=max_workers,
+        max_pending=max_pending,
+        ordered=ordered,
+        on_result=on_result,
+    ) as results:
+        return list(results)

sametime-0.1.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: sametime
+Version: 0.1.0
+Summary: Bounded synchronous thread concurrency for independent I/O operations
+Author: ellainng
+Author-email: ellainng <299958882+ellainng@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/wispsy/sametime
+Project-URL: Repository, https://github.com/wispsy/sametime
+Project-URL: Issues, https://github.com/wispsy/sametime/issues
+Description-Content-Type: text/markdown
+
+# sametime
+
+Bounded synchronous thread concurrency for independent I/O operations.
+
+`sametime` provides structured thread management built directly on Python's standard library `concurrent.futures`. Requires Python 3.14+.
+
+## Highlights
+
+- **Strict Resource Bounds**: Controls both worker count (`max_workers`) and queued futures (`max_pending`), preventing memory ballooning on large/infinite input iterables.
+- **Context-Managed Lifecycle**: Automatic cancellation of pending tasks and graceful thread joins on context exit.
+- **Ordered & Unordered Execution**: Preserve input order or stream results as soon as they complete (`ordered=False`).
+- **Flexible Failure Strategies**: Choose between fail-fast behavior (`thread_map`, `thread_iter`) or indexed outcomes with error capture (`thread_outcomes`).
+- **Consumer-Thread Callbacks**: `on_result` callbacks execute safely on the caller's thread before results are yielded.
+
+## Installation
+
+```sh
+pip install sametime
+```
+
+For development:
+
+```sh
+git clone https://github.com/wispsy/sametime.git
+cd sametime
+uv sync
+```
+
+## Quick Start
+
+### Basic Parallel Mapping
+
+```python
+from sametime import thread_map
+
+results = thread_map(len, ['hello', 'world', 'concurrency'], max_workers=3)
+assert results == [5, 5, 11]
+```
+
+### Streaming Results As They Complete
+
+```python
+from sametime import thread_iter
+
+with thread_iter(fetch, urls, max_workers=4, ordered=False) as stream:
+    for item in stream:
+        handle(item)
+```
+
+### Tolerating Per-Item Errors with `Outcome`
+
+```python
+from sametime import thread_outcomes
+
+with thread_outcomes(int, ['10', 'invalid', '30'], max_pending=2) as results:
+    for outcome in results:
+        if outcome.ok:
+            print(f"Item #{outcome.index} = {outcome.value}")
+        else:
+            print(f"Item #{outcome.index} error: {outcome.error}")
+```
+
+## Documentation
+
+See [docs/api.md](docs/api.md) for full API details, threading guarantees, and design considerations.
+
+## Running Tests
+
+```sh
+python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT

sametime-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+sametime/__init__.py,sha256=eKoSbadypHrWveRWEJCm1fZ8rrVL5M_HujHLLiuizAE,7093
+sametime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sametime-0.1.0.dist-info/licenses/LICENSE,sha256=pAeG0B2X4uxLV9iLuLxEEk4YSQamiNrWf4E6P5vch1Q,1069
+sametime-0.1.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+sametime-0.1.0.dist-info/METADATA,sha256=HOPxoHD22ZhWK-Y7EdaOU8ZOcQcXCZk2-QCRmkzpOJI,2826
+sametime-0.1.0.dist-info/RECORD,,

sametime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any

sametime-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Outside Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.