sametime 0.1.0__tar.gz

sametime-0.1.0/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.

sametime-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,75 @@
+# 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/docs/api.md

@@ -0,0 +1,72 @@
+# sametime API Reference
+
+`sametime` provides bounded synchronous thread concurrency for independent I/O operations, built strictly on Python's standard library (`concurrent.futures.ThreadPoolExecutor`). Requires Python 3.14+.
+
+---
+
+## Design Principles
+
+1. **Explicit Bounds**: `max_workers` controls active threads (defaults to CPU count + 4, capped at 32). `max_pending` bounds the maximum number of submitted, unconsumed futures (defaults to `max_workers * 2`).
+2. **Context Manager Lifetime**: `thread_iter` and `thread_outcomes` are context managers. Exiting the `with` block cancels unstarted futures and joins active threads immediately.
+3. **Consumer-Thread Callbacks**: `on_result` callbacks execute strictly on the consuming thread as results are ready or consumed, avoiding threading races in user state.
+4. **Clean Error Handling**:
+   - `thread_map` / `thread_iter`: Fail fast, re-raising the first exception encountered.
+   - `thread_outcomes`: Captures worker exceptions inside `Outcome` records while letting keyboard interrupts and consumer errors propagate.
+
+---
+
+## API Reference
+
+### `Outcome[R]`
+
+An indexed execution result:
+
+```python
+@dataclass(frozen=True, slots=True)
+class Outcome[R]:
+    index: int
+    value: R | None = None
+    error: Exception | None = field(default=None, repr=False)
+```
+
+- `index: int`: The original 0-based position of the item in the input iterable.
+- `ok: bool`: True if the call succeeded without exception.
+- `result() -> R`: Returns `value` (including `None`), or re-raises `error`.
+
+---
+
+### `thread_map(function, iterable, *, max_workers=None, max_pending=None, ordered=True, on_result=None) -> list[R]`
+
+Runs `function` concurrently over `iterable` using a bounded thread pool, collecting all results into a list.
+- If `ordered=True` (default), preserves the input sequence order in the returned list.
+- Fails fast on the first exception.
+
+---
+
+### `thread_iter(function, iterable, *, max_workers=None, max_pending=None, ordered=True, on_result=None) -> Iterator[Iterator[R]]`
+
+Context manager yielding an iterator of results.
+- `ordered=True` yields results in input order.
+- `ordered=False` yields whichever result finishes first.
+- Bounded input consumption: does not pull infinitely from lazy generators before downstream processing consumes results.
+
+```python
+with thread_iter(fetch_data, urls, max_workers=8, ordered=False) as results:
+    for data in results:
+        process(data)
+```
+
+---
+
+### `thread_outcomes(function, iterable, *, max_workers=None, max_pending=None, ordered=True, on_result=None) -> Iterator[Iterator[Outcome[R]]]`
+
+Context manager yielding `Outcome` objects for both successes and worker failures without interrupting processing of remaining items.
+
+```python
+with thread_outcomes(process_record, records, max_pending=16) as outcomes:
+    for outcome in outcomes:
+        if outcome.ok:
+            print(f"Record {outcome.index} succeeded: {outcome.value}")
+        else:
+            print(f"Record {outcome.index} failed: {outcome.error}")
+```

sametime-0.1.0/examples/thread_jobs.py

@@ -0,0 +1,20 @@
+"""Bounded offline jobs; real I/O functions should set their own timeouts."""
+
+from sametime import thread_iter, thread_map, thread_outcomes
+
+assert thread_map(len, ['one', 'four'], max_workers=2, max_pending=2) == [3, 4]
+with thread_iter(
+    str.upper, ['one', 'two', 'three'], max_workers=2, max_pending=2, ordered=False
+) as results:
+    assert sorted(results) == ['ONE', 'THREE', 'TWO']
+with thread_iter(lambda value: value * 2, range(100), max_workers=2, max_pending=4) as results:
+    assert next(results) == 0
+    # Exiting early cancels queued work and joins running calls.
+observed = []
+with thread_outcomes(int, ['1', 'invalid', '3'], on_result=observed.append) as results:
+    outcomes = list(results)
+assert [row.index for row in outcomes] == [0, 1, 2]
+assert [row.ok for row in outcomes] == [True, False, True]
+assert outcomes[0].result() == 1
+assert len(observed) == 3
+print('Bounded thread jobs passed')

sametime-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "sametime"
+version = "0.1.0"
+description = "Bounded synchronous thread concurrency for independent I/O operations"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "ellainng"
+email = "299958882+ellainng@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/wispsy/sametime"
+Repository = "https://github.com/wispsy/sametime"
+Issues = "https://github.com/wispsy/sametime/issues"
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = [
+    "tests/**",
+    "docs/**",
+    "examples/**",
+    "LICENSE",
+    "README.md",
+]

sametime-0.1.0/pyproject.toml.orig

@@ -0,0 +1,32 @@
+[project]
+name = "sametime"
+version = "0.1.0"
+description = "Bounded synchronous thread concurrency for independent I/O operations"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "ellainng", email = "299958882+ellainng@users.noreply.github.com" }
+]
+requires-python = ">=3.14"
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/wispsy/sametime"
+Repository = "https://github.com/wispsy/sametime"
+Issues = "https://github.com/wispsy/sametime/issues"
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = ["tests/**", "docs/**", "examples/**", "LICENSE", "README.md"]

sametime-0.1.0/src/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/tests/test_sametime.py

@@ -0,0 +1,162 @@
+from concurrent.futures import ThreadPoolExecutor
+import itertools
+import threading
+import unittest
+from unittest.mock import patch
+
+from sametime import thread_iter, thread_map
+
+
+class ThreadTests(unittest.TestCase):
+    def test_empty_values_and_default_workers(self):
+        self.assertEqual(thread_map(len, []), [])
+        self.assertEqual(thread_map(len, ['a', 'abc', 'xy']), [1, 3, 2])
+        self.assertEqual(thread_map(lambda x: x, [None, False, 0]), [None, False, 0])
+        with patch('sametime.os.process_cpu_count', return_value=None):
+            self.assertEqual(thread_map(str, [1]), ['1'])
+
+    def test_actual_overlap_with_a_barrier(self):
+        barrier = threading.Barrier(3, timeout=5)
+        def work(value):
+            barrier.wait()
+            return value * 2
+        self.assertEqual(thread_map(work, [1, 2, 3], max_workers=3, max_pending=3), [2, 4, 6])
+
+    def test_ready_first_unblocks_before_first_input_finishes(self):
+        release = threading.Event()
+        first_started = threading.Event()
+        def work(value):
+            if value == 0:
+                first_started.set()
+                if not release.wait(5):
+                    raise TimeoutError('test worker safety timeout')
+            else:
+                if not first_started.wait(5):
+                    raise TimeoutError('first worker never started')
+            return value
+        try:
+            with thread_iter(work, [0, 1], max_workers=2, ordered=False) as results:
+                self.assertEqual(next(results), 1)
+                release.set()
+                self.assertEqual(list(results), [0])
+        finally:
+            release.set()
+
+    def test_ordered_waits_for_input_order(self):
+        second_done = threading.Event()
+        def work(value):
+            if value == 0:
+                if not second_done.wait(5):
+                    raise TimeoutError('second worker never ran')
+            else:
+                second_done.set()
+            return value
+        self.assertEqual(thread_map(work, [0, 1], max_workers=2), [0, 1])
+
+    def test_lazy_bounded_input_including_completed_unconsumed_results(self):
+        seen = []
+        def source():
+            for value in itertools.count():
+                seen.append(value)
+                yield value
+        with thread_iter(lambda x: x, source(), max_workers=1, max_pending=3) as results:
+            self.assertEqual(seen, [])
+            self.assertEqual(next(results), 0)
+            self.assertEqual(seen, [0, 1, 2])
+            self.assertEqual(next(results), 1)
+            self.assertEqual(seen, [0, 1, 2, 3])
+        self.assertEqual(seen, [0, 1, 2, 3])
+        self.assertEqual(list(results), [])
+
+    def test_worker_exception_identity_and_cleanup(self):
+        error = LookupError('original')
+        threads = []
+        def work(value):
+            threads.append(threading.current_thread())
+            if value == 1:
+                raise error
+            return value
+        with self.assertRaises(LookupError) as raised:
+            thread_map(work, range(10), max_workers=1, max_pending=2)
+        self.assertIs(raised.exception, error)
+        self.assertTrue(all(not thread.is_alive() for thread in threads))
+
+    def test_input_exception_identity_and_cleanup(self):
+        error = OSError('input')
+        threads = []
+        def source():
+            yield 1
+            raise error
+        def work(value):
+            threads.append(threading.current_thread())
+            return value
+        with self.assertRaises(OSError) as raised:
+            thread_map(work, source(), max_workers=1, max_pending=3)
+        self.assertIs(raised.exception, error)
+        self.assertTrue(all(not thread.is_alive() for thread in threads))
+
+    def test_early_exit_cancels_queued_calls_and_joins_running_workers(self):
+        release = threading.Event()
+        started = threading.Event()
+        cancelled = threading.Event()
+        threads = []
+        class RecordingPool(ThreadPoolExecutor):
+            def submit(self, function, *args, **kwargs):
+                future = super().submit(function, *args, **kwargs)
+                future.add_done_callback(lambda done: cancelled.set() if done.cancelled() else None)
+                return future
+        def work(value):
+            threads.append(threading.current_thread())
+            if value == 0:
+                return value
+            if value > 1:
+                raise AssertionError('queued call should be cancelled')
+            started.set()
+            if not release.wait(5):
+                raise TimeoutError('test safety timeout')
+            return value
+        def release_after_cancellation():
+            cancelled.wait(5)
+            release.set()
+        releaser = threading.Thread(target=release_after_cancellation)
+        releaser.start()
+        try:
+            with patch('sametime.ThreadPoolExecutor', RecordingPool):
+                with thread_iter(work, range(10), max_workers=1, max_pending=10) as results:
+                    self.assertEqual(next(results), 0)
+                    self.assertTrue(started.wait(5))
+            self.assertTrue(cancelled.is_set())
+            self.assertEqual(list(results), [])
+            self.assertTrue(all(not thread.is_alive() for thread in threads))
+        finally:
+            release.set()
+            releaser.join(timeout=5)
+
+    def test_unused_context_and_caller_exception(self):
+        def bad_source():
+            raise AssertionError('must remain unconsumed')
+            yield
+        with thread_iter(str, bad_source()) as results:
+            pass
+        self.assertEqual(list(results), [])
+        with self.assertRaisesRegex(RuntimeError, 'caller'):
+            with thread_iter(str, range(100), max_pending=1) as results:
+                self.assertEqual(next(results), '0')
+                raise RuntimeError('caller')
+
+    def test_validation(self):
+        for keyword in ('max_workers', 'max_pending'):
+            for value in (True, 1.5, '2', 0, -1):
+                with self.subTest(keyword=keyword, value=value), self.assertRaises((ValueError, TypeError)):
+                    thread_map(str, [], **{keyword: value})
+        for kwargs in ({'ordered': 1}, {'ordered': None}):
+            with self.assertRaises(TypeError):
+                thread_map(str, [], **kwargs)
+        with self.assertRaises(TypeError):
+            thread_map(None, [])
+        with self.assertRaises(TypeError):
+            thread_map(str, 1)
+
+
+if __name__ == '__main__':
+    unittest.main()

sametime-0.1.0/tests/test_thread_outcomes.py

@@ -0,0 +1,130 @@
+import itertools
+import threading
+import unittest
+
+from sametime import Outcome, thread_iter, thread_map, thread_outcomes
+
+
+class OutcomeTests(unittest.TestCase):
+    def test_mixed_results_original_errors_and_none(self):
+        error = LookupError('original')
+        def work(value):
+            if value == 1:
+                raise error
+            return None if value == 0 else value * 2
+        with thread_outcomes(work, range(3), max_workers=2) as results:
+            rows = list(results)
+        self.assertEqual([row.index for row in rows], [0, 1, 2])
+        self.assertTrue(rows[0].ok)
+        self.assertIsNone(rows[0].result())
+        self.assertFalse(rows[1].ok)
+        self.assertIs(rows[1].error, error)
+        with self.assertRaises(LookupError) as raised:
+            rows[1].result()
+        self.assertIs(raised.exception, error)
+        self.assertEqual(rows[2].result(), 4)
+        self.assertFalse(hasattr(rows[0], 'input'))
+
+    def test_ready_results_keep_original_indices(self):
+        release = threading.Event()
+        def work(value):
+            if value == 0 and not release.wait(5):
+                raise TimeoutError('test safety timeout')
+            return value
+        try:
+            with thread_outcomes(work, [0, 1], max_workers=2, ordered=False) as results:
+                self.assertEqual(next(results).index, 1)
+                release.set()
+                self.assertEqual(next(results).index, 0)
+        finally:
+            release.set()
+
+    def test_callbacks_run_on_consumer_and_before_yield(self):
+        consumer = threading.get_ident()
+        seen = []
+        def observe(row):
+            self.assertEqual(threading.get_ident(), consumer)
+            seen.append(row.index)
+        with thread_outcomes(threading.get_ident, [None]) as results:
+            # Wrong call arity is captured as a normal worker failure.
+            self.assertIsInstance(next(results).error, TypeError)
+        with thread_iter(lambda value: threading.get_ident(), [1, 2], on_result=observe) as results:
+            self.assertNotEqual(next(results), consumer)
+            self.assertEqual(seen, [0])
+        self.assertEqual(seen, [0])
+
+    def test_fail_fast_behavior_and_error_callback(self):
+        error = ValueError('worker')
+        observed = []
+        def work(value):
+            raise error
+        with self.assertRaises(ValueError) as raised:
+            thread_map(work, [0, 1], max_pending=1, on_result=observed.append)
+        self.assertIs(raised.exception, error)
+        self.assertEqual(len(observed), 1)
+        self.assertIs(observed[0].error, error)
+
+    def test_callback_failures_propagate_and_join_workers(self):
+        error = RuntimeError('observer')
+        workers = []
+        def work(value):
+            workers.append(threading.current_thread())
+            return value
+        def observer(row):
+            raise error
+        with self.assertRaises(RuntimeError) as raised:
+            with thread_outcomes(work, range(10), max_workers=2, on_result=observer) as results:
+                next(results)
+        self.assertIs(raised.exception, error)
+        self.assertTrue(all(not worker.is_alive() for worker in workers))
+
+    def test_input_failures_and_base_exceptions_remain_failures(self):
+        def source():
+            yield 1
+            raise OSError('producer')
+        with self.assertRaises(OSError):
+            with thread_outcomes(str, source()) as results:
+                list(results)
+        def stop(value):
+            raise KeyboardInterrupt
+        with self.assertRaises(KeyboardInterrupt):
+            with thread_outcomes(stop, [0]) as results:
+                next(results)
+
+    def test_bounds_empty_inputs_and_unused_context(self):
+        seen = []
+        def source():
+            for value in itertools.count():
+                seen.append(value)
+                yield value
+        with thread_outcomes(str, source(), max_pending=2) as results:
+            self.assertEqual(seen, [])
+            self.assertEqual(next(results).index, 0)
+            self.assertEqual(seen, [0, 1])
+        self.assertEqual(list(results), [])
+        with thread_outcomes(str, []) as results:
+            self.assertEqual(list(results), [])
+        with thread_outcomes(str, source()) as results:
+            pass
+        self.assertEqual(seen, [0, 1])
+        for ordered in (True, False):
+            with thread_outcomes(str, range(9), max_pending=2, ordered=ordered) as results:
+                rows = sorted(results, key=lambda row: row.index)
+            self.assertEqual([row.index for row in rows], list(range(9)))
+            self.assertEqual([row.value for row in rows], list(map(str, range(9))))
+
+    def test_record_and_callback_validation(self):
+        for kwargs in ({'index': True}, {'index': -1}, {'index': 0, 'error': KeyboardInterrupt()},
+                       {'index': 0, 'value': 1, 'error': ValueError()}):
+            with self.assertRaises((TypeError, ValueError)):
+                Outcome(**kwargs)
+        for api in (thread_iter, thread_outcomes):
+            with self.assertRaises(TypeError):
+                with api(str, [], on_result=1):
+                    pass
+        with self.assertRaises(TypeError):
+            thread_map(str, [], on_result=1)
+
+
+if __name__ == '__main__':
+    unittest.main()