streamish 0.1.0__tar.gz

streamish-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run pyright streamish/
+
+      - name: Test
+        run: uv run pytest --cov=streamish --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

streamish-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

streamish-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Testing/Coverage
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+
+# Environment/Secrets
+.env
+.env.*
+
+# OS
+.DS_Store
+
+# Logs
+*.log

streamish-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.14
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+        args: [streamish/]
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        types: [python]
+        pass_filenames: false
+        args: [-q]

streamish-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

streamish-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Francisco
+
+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.

streamish-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: streamish
+Version: 0.1.0
+Summary: Iterator and async iterator utilities for Python
+Project-URL: Homepage, https://github.com/gabfssilva/streamish
+Project-URL: Repository, https://github.com/gabfssilva/streamish
+Author: Gabriel Francisco
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,functional,iterator,pipeline,stream
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# streamish
+
+[![PyPI version](https://img.shields.io/pypi/v/streamish)](https://pypi.org/project/streamish/)
+[![Python](https://img.shields.io/pypi/pyversions/streamish)](https://pypi.org/project/streamish/)
+[![CI](https://github.com/gabfssilva/streamish/actions/workflows/ci.yml/badge.svg)](https://github.com/gabfssilva/streamish/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Iterator and async iterator utilities for Python 3.12+.
+
+## Features
+
+- **Hybrid API**: Fluent chains or standalone functions
+- **Unified sync/async**: Same functions work with both iterators and async iterators
+- **Type safe**: Full pyright strict mode support
+- **Zero dependencies**: stdlib only
+
+## Installation
+
+```bash
+pip install streamish
+```
+
+## Quick Start
+
+```python
+import streamish as st
+
+# Fluent API
+result = list(
+    st.stream([1, 2, 3, 4, 5])
+    .map(lambda x: x * 2)
+    .filter(lambda x: x > 4)
+    .take(2)
+)
+# [6, 8]
+
+# Standalone functions
+result = list(st.take(2, st.filter(lambda x: x > 4, st.map(lambda x: x * 2, [1, 2, 3, 4, 5]))))
+# [6, 8]
+```
+
+## Async Support
+
+Functions automatically detect async iterables and async functions:
+
+```python
+import streamish as st
+
+async def fetch(url: str) -> Response:
+    ...
+
+# Async source
+async def urls():
+    yield "https://example.com/1"
+    yield "https://example.com/2"
+
+# Automatically async
+async for response in st.stream(urls()).map(fetch):
+    print(response)
+
+# Concurrent execution with map_async
+async for response in st.map_async(fetch, urls(), concurrency=10):
+    print(response)
+```
+
+## Operations
+
+### Transform
+
+| Operation | Description |
+|-----------|-------------|
+| `map(fn, it)` | Apply function to each element |
+| `filter(pred, it)` | Keep elements satisfying predicate |
+| `flatten(it)` | Flatten one level of nesting |
+| `flat_map(fn, it)` | Map then flatten |
+| `enumerate(it, start=0)` | Add index to elements |
+| `scan(fn, it, initial=x)` | Cumulative reduce, yielding intermediate values |
+| `map_async(fn, it, concurrency=1)` | Concurrent async map, preserving order |
+
+### Filter
+
+| Operation | Description |
+|-----------|-------------|
+| `take(n, it)` | Take first n elements |
+| `skip(n, it)` | Skip first n elements |
+| `take_while(pred, it)` | Take while predicate is true |
+| `skip_while(pred, it)` | Skip while predicate is true |
+| `distinct(it)` | Remove duplicates |
+| `distinct_by(key_fn, it)` | Remove duplicates by key |
+
+### Group
+
+| Operation | Description |
+|-----------|-------------|
+| `batch(size, it, timeout=None)` | Group into batches by size or timeout |
+| `window(size, it, step=1)` | Sliding window |
+| `partition(pred, it)` | Split into (matches, non_matches) |
+
+### Combine
+
+| Operation | Description |
+|-----------|-------------|
+| `zip(*iterables)` | Zip iterables together |
+| `chain(*iterables)` | Chain iterables sequentially |
+| `interleave(*iterables)` | Alternate elements round-robin |
+| `merge(*async_iterables)` | Merge async iterables, emit as they arrive |
+
+## Examples
+
+### Processing a file line by line
+
+```python
+import streamish as st
+
+with open("data.txt") as f:
+    result = list(
+        st.stream(f)
+        .map(str.strip)
+        .filter(bool)  # skip empty lines
+        .distinct()
+        .take(100)
+    )
+```
+
+### Batching API requests
+
+```python
+import streamish as st
+
+async def send_batch(items: list[Item]) -> None:
+    ...
+
+async def process(items: AsyncIterable[Item]) -> None:
+    async for batch in st.stream(items).batch(100, timeout=5.0):
+        await send_batch(batch)
+```
+
+### Concurrent HTTP requests
+
+```python
+import httpx
+import streamish as st
+
+async def fetch(client: httpx.AsyncClient, url: str) -> Response:
+    return await client.get(url)
+
+async def main():
+    urls = ["https://example.com/1", "https://example.com/2", ...]
+
+    async with httpx.AsyncClient() as client:
+        async for response in st.map_async(
+            lambda url: fetch(client, url),
+            urls,
+            concurrency=10,
+        ):
+            print(response.status_code)
+```
+
+### Windowed statistics
+
+```python
+import streamish as st
+
+# Moving average over last 5 values
+values = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+
+averages = list(
+    st.stream(values)
+    .window(5)
+    .map(lambda w: sum(w) / len(w))
+)
+# [3.0, 4.0, 5.0, 6.0, 7.0, 8.0]
+```
+
+### Merging async streams
+
+```python
+import streamish as st
+
+async def stream_a():
+    for i in range(3):
+        await asyncio.sleep(0.1)
+        yield f"a{i}"
+
+async def stream_b():
+    for i in range(3):
+        await asyncio.sleep(0.15)
+        yield f"b{i}"
+
+# Items emitted as they arrive
+async for item in st.merge(stream_a(), stream_b()):
+    print(item)
+# a0, b0, a1, a2, b1, b2 (order depends on timing)
+```
+
+## License
+
+MIT

streamish-0.1.0/README.md

@@ -0,0 +1,198 @@
+# streamish
+
+[![PyPI version](https://img.shields.io/pypi/v/streamish)](https://pypi.org/project/streamish/)
+[![Python](https://img.shields.io/pypi/pyversions/streamish)](https://pypi.org/project/streamish/)
+[![CI](https://github.com/gabfssilva/streamish/actions/workflows/ci.yml/badge.svg)](https://github.com/gabfssilva/streamish/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Iterator and async iterator utilities for Python 3.12+.
+
+## Features
+
+- **Hybrid API**: Fluent chains or standalone functions
+- **Unified sync/async**: Same functions work with both iterators and async iterators
+- **Type safe**: Full pyright strict mode support
+- **Zero dependencies**: stdlib only
+
+## Installation
+
+```bash
+pip install streamish
+```
+
+## Quick Start
+
+```python
+import streamish as st
+
+# Fluent API
+result = list(
+    st.stream([1, 2, 3, 4, 5])
+    .map(lambda x: x * 2)
+    .filter(lambda x: x > 4)
+    .take(2)
+)
+# [6, 8]
+
+# Standalone functions
+result = list(st.take(2, st.filter(lambda x: x > 4, st.map(lambda x: x * 2, [1, 2, 3, 4, 5]))))
+# [6, 8]
+```
+
+## Async Support
+
+Functions automatically detect async iterables and async functions:
+
+```python
+import streamish as st
+
+async def fetch(url: str) -> Response:
+    ...
+
+# Async source
+async def urls():
+    yield "https://example.com/1"
+    yield "https://example.com/2"
+
+# Automatically async
+async for response in st.stream(urls()).map(fetch):
+    print(response)
+
+# Concurrent execution with map_async
+async for response in st.map_async(fetch, urls(), concurrency=10):
+    print(response)
+```
+
+## Operations
+
+### Transform
+
+| Operation | Description |
+|-----------|-------------|
+| `map(fn, it)` | Apply function to each element |
+| `filter(pred, it)` | Keep elements satisfying predicate |
+| `flatten(it)` | Flatten one level of nesting |
+| `flat_map(fn, it)` | Map then flatten |
+| `enumerate(it, start=0)` | Add index to elements |
+| `scan(fn, it, initial=x)` | Cumulative reduce, yielding intermediate values |
+| `map_async(fn, it, concurrency=1)` | Concurrent async map, preserving order |
+
+### Filter
+
+| Operation | Description |
+|-----------|-------------|
+| `take(n, it)` | Take first n elements |
+| `skip(n, it)` | Skip first n elements |
+| `take_while(pred, it)` | Take while predicate is true |
+| `skip_while(pred, it)` | Skip while predicate is true |
+| `distinct(it)` | Remove duplicates |
+| `distinct_by(key_fn, it)` | Remove duplicates by key |
+
+### Group
+
+| Operation | Description |
+|-----------|-------------|
+| `batch(size, it, timeout=None)` | Group into batches by size or timeout |
+| `window(size, it, step=1)` | Sliding window |
+| `partition(pred, it)` | Split into (matches, non_matches) |
+
+### Combine
+
+| Operation | Description |
+|-----------|-------------|
+| `zip(*iterables)` | Zip iterables together |
+| `chain(*iterables)` | Chain iterables sequentially |
+| `interleave(*iterables)` | Alternate elements round-robin |
+| `merge(*async_iterables)` | Merge async iterables, emit as they arrive |
+
+## Examples
+
+### Processing a file line by line
+
+```python
+import streamish as st
+
+with open("data.txt") as f:
+    result = list(
+        st.stream(f)
+        .map(str.strip)
+        .filter(bool)  # skip empty lines
+        .distinct()
+        .take(100)
+    )
+```
+
+### Batching API requests
+
+```python
+import streamish as st
+
+async def send_batch(items: list[Item]) -> None:
+    ...
+
+async def process(items: AsyncIterable[Item]) -> None:
+    async for batch in st.stream(items).batch(100, timeout=5.0):
+        await send_batch(batch)
+```
+
+### Concurrent HTTP requests
+
+```python
+import httpx
+import streamish as st
+
+async def fetch(client: httpx.AsyncClient, url: str) -> Response:
+    return await client.get(url)
+
+async def main():
+    urls = ["https://example.com/1", "https://example.com/2", ...]
+
+    async with httpx.AsyncClient() as client:
+        async for response in st.map_async(
+            lambda url: fetch(client, url),
+            urls,
+            concurrency=10,
+        ):
+            print(response.status_code)
+```
+
+### Windowed statistics
+
+```python
+import streamish as st
+
+# Moving average over last 5 values
+values = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+
+averages = list(
+    st.stream(values)
+    .window(5)
+    .map(lambda w: sum(w) / len(w))
+)
+# [3.0, 4.0, 5.0, 6.0, 7.0, 8.0]
+```
+
+### Merging async streams
+
+```python
+import streamish as st
+
+async def stream_a():
+    for i in range(3):
+        await asyncio.sleep(0.1)
+        yield f"a{i}"
+
+async def stream_b():
+    for i in range(3):
+        await asyncio.sleep(0.15)
+        yield f"b{i}"
+
+# Items emitted as they arrive
+async for item in st.merge(stream_a(), stream_b()):
+    print(item)
+# a0, b0, a1, a2, b1, b2 (order depends on timing)
+```
+
+## License
+
+MIT

streamish-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "streamish"
+version = "0.1.0"
+description = "Iterator and async iterator utilities for Python"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Gabriel Francisco" }]
+keywords = ["iterator", "async", "stream", "functional", "pipeline"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/gabfssilva/streamish"
+Repository = "https://github.com/gabfssilva/streamish"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D",        # docstrings (optional for library)
+    "COM812",   # trailing comma (conflicts with formatter)
+    "ISC001",   # implicit string concat (conflicts with formatter)
+    "A004",     # shadowing builtins is intentional (map, filter, enumerate)
+    "EM101",    # string literals in exceptions ok for simple errors
+    "TRY003",   # long exception messages ok
+    "TRY300",   # return in try ok for simple cases
+    "RUF022",   # __all__ sorting not required
+    "SLOT000",  # __slots__ false positive on generic class
+    "E501",     # line length handled by formatter
+    "C901",     # complexity ok for async streaming functions
+    "PLR0912",  # branches ok for async streaming functions
+    "SIM113",   # enumerate suggestion not always better
+    "PERF401",  # list comprehension not possible with await
+    "UP028",    # yield from not possible when retuning tuple
+    "ASYNC109", # timeout parameter naming is intentional
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "PLR2004"]  # assert, magic values ok in tests
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=4.0",
+    "pyright>=1.1",
+    "ruff>=0.14",
+    "pre-commit>=4.5.1",
+]

streamish-0.1.0/streamish/__init__.py

@@ -0,0 +1,63 @@
+"""Streamish - Iterator and async iterator utilities."""
+
+from collections.abc import AsyncIterable, Iterable
+
+from streamish.ops import (
+    batch,
+    chain,
+    chain_async,
+    distinct,
+    distinct_by,
+    enumerate,
+    filter,
+    flat_map,
+    flatten,
+    interleave,
+    map,
+    map_async,
+    merge,
+    partition,
+    partition_async,
+    scan,
+    skip,
+    skip_while,
+    take,
+    take_while,
+    window,
+    zip,
+    zip_async,
+)
+from streamish.stream import Stream
+
+__all__ = [
+    "stream",
+    "Stream",
+    "map",
+    "map_async",
+    "filter",
+    "take",
+    "skip",
+    "take_while",
+    "skip_while",
+    "distinct",
+    "distinct_by",
+    "flatten",
+    "flat_map",
+    "enumerate",
+    "scan",
+    "batch",
+    "window",
+    "partition",
+    "partition_async",
+    "zip",
+    "zip_async",
+    "chain",
+    "chain_async",
+    "interleave",
+    "merge",
+]
+
+
+def stream[T](source: Iterable[T] | AsyncIterable[T]) -> Stream[T]:
+    """Create a Stream from an iterable or async iterable."""
+    return Stream(source)