pydantic-linq 0.1.0__tar.gz

pydantic_linq-0.1.0/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"f6433955-3966-47db-80fb-3ba5bc285b56","pid":24568,"procStart":"134378175680740197","acquiredAt":1793345293783}

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

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uvx ruff check
+      - run: uv sync --locked && uvx pyright src
+
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run pytest -q
+      - name: Examples
+        shell: bash
+        run: for f in examples/*.py; do uv run python "$f" > /dev/null || exit 1; done

pydantic_linq-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - name: Tag matches pyproject version
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          test "v$version" = "$GITHUB_REF_NAME" || { echo "::error::tag $GITHUB_REF_NAME != pyproject v$version"; exit 1; }
+      - run: uv build
+      - name: Smoke-test the wheel
+        run: uv run --isolated --no-project --with ./dist/*.whl python -c "import pydantic_linq; assert [1, 2].select(str).to_list() == ['1', '2']"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    # PyPI trusted publisher: owner codejunction, repo pydantic-linq, workflow release.yml, environment pypi
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pydantic-linq/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  github-release:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --title "pydantic-linq $GITHUB_REF_NAME" --generate-notes

pydantic_linq-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/

pydantic_linq-0.1.0/LICENSE

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

pydantic_linq-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: pydantic-linq
+Version: 0.1.0
+Summary: C# LINQ (Enumerable + AsyncEnumerable) for Python, typed and Pydantic-aware
+Project-URL: Homepage, https://github.com/codejunction/pydantic-linq
+Project-URL: Source, https://github.com/codejunction/pydantic-linq
+Project-URL: Issues, https://github.com/codejunction/pydantic-linq/issues
+Author-email: Abhishek Dutta <phoenixdutta@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,collections,functional,iterator,linq,pydantic,query
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: forbiddenfruit>=0.1.4
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# pydantic-linq
+
+C# LINQ (`System.Linq.Enumerable`) for Python. It is typed and works with Pydantic.
+
+```python
+from pydantic import BaseModel
+import pydantic_linq  # adds LINQ operators to list / tuple / set / frozenset
+
+class Row(BaseModel):
+    id: int
+    tag: str
+
+rows = [Row(id=1, tag="a"), Row(id=2, tag="b"), Row(id=3, tag="a")]
+
+rows.where(lambda r: r.tag == "a").select(lambda r: r.id).to_list()   # [1, 3]
+rows.group_by(lambda r: r.tag).select(lambda g: (g.key, len(g))).to_list()
+rows.order_by_descending(lambda r: r.id).then_by(lambda r: r.tag).first()
+```
+
+## Async
+
+`AsyncEnumerable` covers System.Linq.Async. It wraps any sync or async iterable. Sequence operators are deferred, and terminal operators are awaited:
+
+```python
+async def load_age(r: Row) -> int: ...
+
+ages = await rows.to_async_enumerable().where(lambda r: r.id > 1).select(load_age).to_list()
+```
+
+A selector or predicate can be a plain function or an `async def`, so there are no separate `*Await` overloads. Terminal operators keep the sync names (`to_list`, `first`, `count`) and are awaited. The C# `Async` suffix is dropped.
+
+## Conventions
+
+- Method names are the C# names in snake_case: `OrderByDescending` becomes `order_by_descending`. `Except` becomes `except_`, because `except` is a Python keyword.
+- Operators that return a sequence are deferred and can be enumerated again, as in .NET.
+- Equality uses value semantics (`==`). Non-frozen (unhashable) pydantic models work in `distinct`, `union` and the other set operators.
+- `cast(Model)` validates each element with a pydantic `TypeAdapter`, so dicts become models. `of_type(Model)` filters with `isinstance`.
+- `Enumerable[Model]` can be a pydantic field type. It validates like `list[Model]` and serializes as a list.
+- C# `KeyValuePair` becomes a `(key, value)` tuple. `IComparer` becomes a `cmp(a, b) -> int` function. A C# `Range` or `Index` (for example `^1`) becomes a slice or a negative int.
+- Lambda overloads that take an index (`Select((x, i) => ...)`) map to `.index()`, followed by the operator.
+- Empty-sequence errors raise `InvalidOperationError`, which subclasses `ValueError`.
+
+## Builtin patching
+
+Importing the package uses [forbiddenfruit](https://github.com/clarete/forbiddenfruit) to patch `list`, `tuple`, `set` and `frozenset`. A builtin method that already exists keeps its Python meaning, for example `list.count(x)` and `list.reverse()`. To get the LINQ version, use `rows.as_enumerable().count()`. Type checkers do not see the patched methods. Where you need static types, use `Enumerable(rows)`. To remove the patches, call `pydantic_linq.uninstall()`.
+
+## Layout
+
+```
+src/pydantic_linq/
+  core/           errors, value-equality set, Grouping (no internal deps)
+  sync/
+    base.py       EnumerableBase, deferred execution
+    operators/    one mixin per LINQ category: filtering, projection, partitioning, sets, sorting, ...
+    enumerable.py Enumerable = all mixins
+    ordered.py    OrderedEnumerable (then_by)
+    grouping.py   Grouping (an Enumerable with .key), Lookup
+  aio/            AsyncEnumerable, same layout as sync/
+  integrations/   pydantic field schema, builtin patching
+```
+
+## Examples
+
+`examples/` runs from simple to complex: `01_basics` through `07_sales_report`, an end-to-end report pipeline. Run any of them with `uv run python examples/01_basics.py`.
+

pydantic_linq-0.1.0/README.md

@@ -0,0 +1,65 @@
+# pydantic-linq
+
+C# LINQ (`System.Linq.Enumerable`) for Python. It is typed and works with Pydantic.
+
+```python
+from pydantic import BaseModel
+import pydantic_linq  # adds LINQ operators to list / tuple / set / frozenset
+
+class Row(BaseModel):
+    id: int
+    tag: str
+
+rows = [Row(id=1, tag="a"), Row(id=2, tag="b"), Row(id=3, tag="a")]
+
+rows.where(lambda r: r.tag == "a").select(lambda r: r.id).to_list()   # [1, 3]
+rows.group_by(lambda r: r.tag).select(lambda g: (g.key, len(g))).to_list()
+rows.order_by_descending(lambda r: r.id).then_by(lambda r: r.tag).first()
+```
+
+## Async
+
+`AsyncEnumerable` covers System.Linq.Async. It wraps any sync or async iterable. Sequence operators are deferred, and terminal operators are awaited:
+
+```python
+async def load_age(r: Row) -> int: ...
+
+ages = await rows.to_async_enumerable().where(lambda r: r.id > 1).select(load_age).to_list()
+```
+
+A selector or predicate can be a plain function or an `async def`, so there are no separate `*Await` overloads. Terminal operators keep the sync names (`to_list`, `first`, `count`) and are awaited. The C# `Async` suffix is dropped.
+
+## Conventions
+
+- Method names are the C# names in snake_case: `OrderByDescending` becomes `order_by_descending`. `Except` becomes `except_`, because `except` is a Python keyword.
+- Operators that return a sequence are deferred and can be enumerated again, as in .NET.
+- Equality uses value semantics (`==`). Non-frozen (unhashable) pydantic models work in `distinct`, `union` and the other set operators.
+- `cast(Model)` validates each element with a pydantic `TypeAdapter`, so dicts become models. `of_type(Model)` filters with `isinstance`.
+- `Enumerable[Model]` can be a pydantic field type. It validates like `list[Model]` and serializes as a list.
+- C# `KeyValuePair` becomes a `(key, value)` tuple. `IComparer` becomes a `cmp(a, b) -> int` function. A C# `Range` or `Index` (for example `^1`) becomes a slice or a negative int.
+- Lambda overloads that take an index (`Select((x, i) => ...)`) map to `.index()`, followed by the operator.
+- Empty-sequence errors raise `InvalidOperationError`, which subclasses `ValueError`.
+
+## Builtin patching
+
+Importing the package uses [forbiddenfruit](https://github.com/clarete/forbiddenfruit) to patch `list`, `tuple`, `set` and `frozenset`. A builtin method that already exists keeps its Python meaning, for example `list.count(x)` and `list.reverse()`. To get the LINQ version, use `rows.as_enumerable().count()`. Type checkers do not see the patched methods. Where you need static types, use `Enumerable(rows)`. To remove the patches, call `pydantic_linq.uninstall()`.
+
+## Layout
+
+```
+src/pydantic_linq/
+  core/           errors, value-equality set, Grouping (no internal deps)
+  sync/
+    base.py       EnumerableBase, deferred execution
+    operators/    one mixin per LINQ category: filtering, projection, partitioning, sets, sorting, ...
+    enumerable.py Enumerable = all mixins
+    ordered.py    OrderedEnumerable (then_by)
+    grouping.py   Grouping (an Enumerable with .key), Lookup
+  aio/            AsyncEnumerable, same layout as sync/
+  integrations/   pydantic field schema, builtin patching
+```
+
+## Examples
+
+`examples/` runs from simple to complex: `01_basics` through `07_sales_report`, an end-to-end report pipeline. Run any of them with `uv run python examples/01_basics.py`.
+

pydantic_linq-0.1.0/examples/01_basics.py

@@ -0,0 +1,37 @@
+"""Basics: filter, project and pick elements from a plain list of pydantic models."""
+
+from pydantic import BaseModel
+
+import pydantic_linq  # noqa: F401  (adds the LINQ operators to list / tuple / set)
+from pydantic_linq import Enumerable
+
+
+class Product(BaseModel):
+    name: str
+    price: float
+    stock: int
+
+
+products = [
+    Product(name="Keyboard", price=49.0, stock=12),
+    Product(name="Mouse", price=19.5, stock=0),
+    Product(name="Monitor", price=219.0, stock=4),
+    Product(name="Cable", price=5.0, stock=120),
+]
+
+# Where + Select, called straight on the list
+in_stock = products.where(lambda p: p.stock > 0).select(lambda p: p.name).to_list()
+print("in stock:", in_stock)
+
+# Element operators
+print("first over $100:", products.first(lambda p: p.price > 100).name)
+print("first over $1000:", products.first_or_default(lambda p: p.price > 1000))
+
+# Quantifiers and counting. list.count(x) keeps its Python meaning, so wrap for the LINQ count().
+print("any sold out:", products.any(lambda p: p.stock == 0))
+print("sold out count:", Enumerable(products).count(lambda p: p.stock == 0))
+
+# Queries are deferred: nothing runs until you enumerate
+cheap = products.where(lambda p: p.price < 20)
+products.append(Product(name="Sticker", price=1.0, stock=500))
+print("cheap (evaluated now):", cheap.select(lambda p: p.name).to_list())

pydantic_linq-0.1.0/examples/02_sorting_paging.py

@@ -0,0 +1,36 @@
+"""Sorting and paging: OrderBy / ThenBy, Skip / Take, Chunk."""
+
+from pydantic import BaseModel
+
+import pydantic_linq  # noqa: F401
+
+
+class Employee(BaseModel):
+    name: str
+    dept: str
+    salary: int
+
+
+staff = [
+    Employee(name="Ava", dept="Eng", salary=120),
+    Employee(name="Ben", dept="Ops", salary=90),
+    Employee(name="Cleo", dept="Eng", salary=120),
+    Employee(name="Dan", dept="Eng", salary=105),
+    Employee(name="Eve", dept="Ops", salary=95),
+]
+
+# Multi-key, stable sort: dept ascending, then salary descending, then name
+ordered = staff.order_by(lambda e: e.dept).then_by_descending(lambda e: e.salary).then_by(lambda e: e.name)
+print([f"{e.dept}:{e.name}:{e.salary}" for e in ordered])
+
+# Paging
+page_size = 2
+for page in range(3):
+    names = ordered.skip(page * page_size).take(page_size).select(lambda e: e.name).to_list()
+    print(f"page {page + 1}:", names)
+
+# Chunk does the same in one call
+print("chunks:", ordered.select(lambda e: e.name).chunk(2).to_list())
+
+# Take with a range: slice(1, -1) is C#'s Take(1..^1)
+print("without top and bottom:", ordered.take(slice(1, -1)).select(lambda e: e.name).to_list())

pydantic_linq-0.1.0/examples/03_grouping_aggregation.py

@@ -0,0 +1,47 @@
+"""Grouping and aggregation: GroupBy, ToLookup, CountBy, AggregateBy, Sum / Average / MaxBy."""
+
+from datetime import date
+
+from pydantic import BaseModel
+
+import pydantic_linq  # noqa: F401
+
+
+class Sale(BaseModel):
+    region: str
+    rep: str
+    amount: float
+    day: date
+
+
+sales = [
+    Sale(region="North", rep="Ann", amount=120.0, day=date(2026, 1, 3)),
+    Sale(region="North", rep="Bob", amount=80.0, day=date(2026, 1, 4)),
+    Sale(region="South", rep="Cid", amount=200.0, day=date(2026, 1, 4)),
+    Sale(region="North", rep="Ann", amount=60.0, day=date(2026, 2, 1)),
+    Sale(region="South", rep="Dee", amount=40.0, day=date(2026, 2, 2)),
+]
+
+# GroupBy with a result selector: one summary row per region
+summary = sales.group_by(
+    lambda s: s.region,
+    result_selector=lambda region, items: (region, items.count(), items.sum(lambda s: s.amount)),
+).to_list()
+print("region, orders, total:", summary)
+
+# Each Grouping is itself an Enumerable with a .key
+for g in sales.group_by(lambda s: s.day.month):
+    print(f"month {g.key}: avg {g.average(lambda s: s.amount):.2f}, reps {g.select(lambda s: s.rep).distinct().to_list()}")
+
+# A Lookup is an indexable group set; a missing key gives an empty sequence
+by_rep = sales.to_lookup(lambda s: s.rep, lambda s: s.amount)
+print("Ann:", by_rep["Ann"].to_list(), "Zed:", by_rep["Zed"].to_list())
+
+# .NET 9 CountBy / AggregateBy
+print("orders per rep:", sales.count_by(lambda s: s.rep).to_list())
+print("revenue per rep:", sales.aggregate_by(lambda s: s.rep, 0.0, lambda acc, s: acc + s.amount).to_list())
+
+# Scalar aggregates
+print("total:", sales.sum(lambda s: s.amount))
+print("biggest sale:", sales.max_by(lambda s: s.amount).rep)
+print("running product:", [1, 2, 3, 4].aggregate(lambda a, b: a * b))

pydantic_linq-0.1.0/examples/04_joins_sets.py

@@ -0,0 +1,60 @@
+"""Joins and set operations across two model lists."""
+
+from pydantic import BaseModel
+
+import pydantic_linq  # noqa: F401
+
+
+class Customer(BaseModel):
+    id: int
+    name: str
+
+
+class Order(BaseModel):
+    customer_id: int
+    item: str
+
+
+customers = [Customer(id=1, name="Ann"), Customer(id=2, name="Bob"), Customer(id=3, name="Cid")]
+orders = [
+    Order(customer_id=1, item="book"),
+    Order(customer_id=1, item="pen"),
+    Order(customer_id=3, item="lamp"),
+    Order(customer_id=9, item="ghost"),
+]
+
+# Inner join
+print("join:", customers.join(orders, lambda c: c.id, lambda o: o.customer_id, lambda c, o: (c.name, o.item)).to_list())
+
+# GroupJoin: every customer with their orders (possibly none)
+print(
+    "group join:",
+    customers.group_join(
+        orders, lambda c: c.id, lambda o: o.customer_id, lambda c, os: (c.name, os.select(lambda o: o.item).to_list())
+    ).to_list(),
+)
+
+# .NET 10 LeftJoin / RightJoin: the missing side is None
+print(
+    "left join:",
+    customers.left_join(
+        orders, lambda c: c.id, lambda o: o.customer_id, lambda c, o: (c.name, o.item if o else None)
+    ).to_list(),
+)
+print(
+    "right join:",
+    customers.right_join(
+        orders, lambda c: c.id, lambda o: o.customer_id, lambda c, o: (c.name if c else None, o.item)
+    ).to_list(),
+)
+
+# Set operations use value equality, so equal (non-frozen) models count as duplicates
+batch_a = [Customer(id=1, name="Ann"), Customer(id=2, name="Bob")]
+batch_b = [Customer(id=2, name="Bob"), Customer(id=4, name="Dee")]
+print("union:", batch_a.union(batch_b).select(lambda c: c.name).to_list())
+print("intersect:", batch_a.intersect(batch_b).select(lambda c: c.name).to_list())
+print("except:", batch_a.except_(batch_b).select(lambda c: c.name).to_list())
+
+# *By variants compare by a key; the second sequence holds keys
+print("customers without orders:", customers.except_by(orders.select(lambda o: o.customer_id), lambda c: c.id)
+      .select(lambda c: c.name).to_list())

pydantic_linq-0.1.0/examples/05_pydantic_integration.py

@@ -0,0 +1,54 @@
+"""Pydantic integration: validate raw data with cast(), use Enumerable[Model] as a field, round-trip JSON."""
+
+from pydantic import BaseModel, ValidationError
+
+import pydantic_linq  # noqa: F401
+from pydantic_linq import Enumerable
+
+
+class LineItem(BaseModel):
+    sku: str
+    qty: int
+    unit_price: float
+
+
+class Invoice(BaseModel):
+    number: str
+    lines: Enumerable[LineItem]  # validated like list[LineItem]; behaves like LINQ
+
+    @property
+    def total(self) -> float:
+        return self.lines.sum(lambda line: line.qty * line.unit_price)
+
+
+# Raw rows, e.g. from an API or CSV: strings get coerced, dicts become models
+raw = [
+    {"sku": "A-1", "qty": "2", "unit_price": "9.99"},
+    {"sku": "B-7", "qty": 1, "unit_price": 120},
+]
+items = raw.cast(LineItem).to_list()
+print("cast:", items)
+
+# strict=True disables coercion
+try:
+    raw.cast(LineItem, strict=True).to_list()
+except ValidationError as e:
+    print("strict cast failed:", e.error_count(), "errors")
+
+invoice = Invoice(number="INV-1", lines=items)
+print("total:", round(invoice.total, 2))
+print("big lines:", invoice.lines.where(lambda line: line.unit_price > 50).select(lambda line: line.sku).to_list())
+
+# Serializes as a plain list; validates back into an Enumerable
+payload = invoice.model_dump_json()
+print("json:", payload)
+again = Invoice.model_validate_json(payload)
+print("round-trip type:", type(again.lines).__name__, "count:", again.lines.count())
+
+# Value equality: non-frozen models are unhashable, distinct() still works
+dupes = [LineItem(sku="A-1", qty=1, unit_price=1.0)] * 3
+print("distinct:", dupes.distinct().count())
+
+# of_type filters by class, like OfType<T>
+mixed = [items[0], "noise", 42, items[1]]
+print("of_type:", mixed.of_type(LineItem).select(lambda line: line.sku).to_list())

pydantic_linq-0.1.0/examples/06_async.py

@@ -0,0 +1,67 @@
+"""Async: AsyncEnumerable over async sources, with sync or async selectors."""
+
+import asyncio
+
+from pydantic import BaseModel
+
+import pydantic_linq  # noqa: F401
+from pydantic_linq import AsyncEnumerable
+
+
+class User(BaseModel):
+    id: int
+    name: str
+
+
+class Profile(BaseModel):
+    user_id: int
+    followers: int
+
+
+async def fetch_users():
+    """An async generator source, e.g. a paginated API or a DB cursor."""
+    for i, name in enumerate(["ann", "bob", "cid", "dee"], start=1):
+        await asyncio.sleep(0.01)
+        yield User(id=i, name=name)
+
+
+async def fetch_profile(user: User) -> Profile:
+    """An async selector, the System.Linq.Async SelectAwait overload."""
+    await asyncio.sleep(0.01)
+    return Profile(user_id=user.id, followers=user.id * 150)
+
+
+async def is_active(user: User) -> bool:
+    await asyncio.sleep(0)
+    return user.id != 2
+
+
+async def main() -> None:
+    users = AsyncEnumerable(fetch_users())
+
+    # Async predicate + sync projection
+    names = await users.where(is_active).select(lambda u: u.name.title()).to_list()
+    print("active:", names)
+
+    # Async generator sources are one-shot (as in Python), so re-wrap for a second query
+    users = AsyncEnumerable(fetch_users())
+    popular = await (
+        users.select(fetch_profile)
+        .where(lambda p: p.followers > 200)
+        .order_by_descending(lambda p: p.followers)
+        .select(lambda p: p.user_id)
+        .to_list()
+    )
+    print("popular ids:", popular)
+
+    # Sync lists enter async with to_async_enumerable(); terminal operators are awaited
+    local = [User(id=10, name="eve"), User(id=11, name="fay")]
+    print("total followers:", await local.to_async_enumerable().select(fetch_profile).sum(lambda p: p.followers))
+    print("first:", (await local.to_async_enumerable().first(lambda u: u.id > 10)).name)
+
+    # Grouping yields AsyncGrouping, an AsyncEnumerable with a .key
+    async for g in AsyncEnumerable(fetch_users()).group_by(lambda u: u.id % 2 == 0):
+        print("even" if g.key else "odd", await g.select(lambda u: u.name).to_list())
+
+
+asyncio.run(main())