Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/reference/array.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,12 @@

# Typed Array

Integer indexing preserves the element type: `TypedArray[int]([1, 2])[0]`
has type `int`. Slice indexing returns the underlying storage's mutable sequence,
not another `TypedArray`. Type checking also checks individual assignments and
slice replacement elements against the array's element type.

```{eval-rst}
.. automodule:: expression.collections.array
:members:
```
```
6 changes: 6 additions & 0 deletions docs/reference/collections.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,12 @@ while `skip_last(0)` preserves all elements. For example,
`AsyncSeq.take(n)` consumes at most `n` source items. Taking zero items does not
advance the source, and completing the result does not request an extra item.

`sum` and `sum_by` use Python's summation behavior: empty input returns integer
`0`, even when the element or projection type is `float` or `Decimal`. Their
return annotations include this empty-input case. `sum_by` requires summable
projection results, not summable source elements; for example,
`Block.of("one", "four").sum_by(len)` returns `7`.

## Additional modules

```{eval-rst}
Expand Down
42 changes: 29 additions & 13 deletions expression/collections/array.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,10 @@
import array
import builtins
import functools
import operator
from collections.abc import Callable, Iterable, Iterator, MutableSequence
from enum import Enum
from typing import Any, cast
from typing import Any, Literal, SupportsIndex, cast, overload

from expression.core import (
NOTHING,
Expand All @@ -30,7 +31,7 @@
from . import seq


type _Array[TSourceSum: SupportsSum] = list[TSourceSum] | MutableSequence[TSourceSum]
type _Array[TSource] = MutableSequence[TSource]


class int8(int): ...
Expand Down Expand Up @@ -174,7 +175,7 @@ def __init__(
else:
arr, typecode = array_from_initializer(initializer)

self.value: _Array[Any] = arr
self.value: _Array[TSource] = arr
self.typecode = typecode

def map[TResult](self, mapping: Callable[[TSource], TResult]) -> TypedArray[TResult]:
Expand Down Expand Up @@ -364,10 +365,10 @@ def sort_with(self, func: Callable[[TSource], Any], reverse: bool = False) -> Ty
"""
return TypedArray(builtins.sorted(self.value, key=func, reverse=reverse))

def sum[TSourceSum: SupportsSum](self: TypedArray[TSourceSum]) -> int:
def sum[TSourceSum: SupportsSum](self: TypedArray[TSourceSum]) -> TSourceSum | Literal[0]:
return sum(self)

def sum_by[TSourceSum: SupportsSum](self, projection: Callable[[TSource], TSourceSum]) -> int:
def sum_by[TSourceSum: SupportsSum](self, projection: Callable[[TSource], TSourceSum]) -> TSourceSum | Literal[0]:
return pipe(
self,
sum_by(projection),
Expand Down Expand Up @@ -410,13 +411,13 @@ def try_head(self) -> Option[TSource]:
empty.
"""
if self.value:
value = cast("TSource", self.value[0])
value = self.value[0]
return Some(value)

return NOTHING

@staticmethod
def unfold[TResult, TState](
def unfold[TState, TResult](
generator: Callable[[TState], Option[tuple[TResult, TState]]], state: TState
) -> TypedArray[TResult]:
"""Unfold array.
Expand Down Expand Up @@ -451,11 +452,26 @@ def __len__(self) -> int:
def __iter__(self) -> Iterator[TSource]:
return iter(self.value)

def __setitem__(self, key: slice | int, value: Any) -> None:
self.value[key] = value
@overload
def __setitem__(self, key: SupportsIndex, value: TSource) -> None: ...

def __getitem__(self, key: Any) -> Any:
return self.value[key]
@overload
def __setitem__(self, key: slice, value: Iterable[TSource]) -> None: ...

def __setitem__(self, key: slice | SupportsIndex, value: TSource | Iterable[TSource]) -> None:
if isinstance(key, slice):
self.value[key] = cast(Iterable[TSource], value)
else:
self.value[operator.index(key)] = cast(TSource, value)

@overload
def __getitem__(self, key: SupportsIndex) -> TSource: ...

@overload
def __getitem__(self, key: slice) -> MutableSequence[TSource]: ...

def __getitem__(self, key: slice | SupportsIndex) -> TSource | MutableSequence[TSource]:
return self.value[key] if isinstance(key, slice) else self.value[operator.index(key)]

def __delitem__(self, key: slice | int) -> None:
del self.value[key]
Expand Down Expand Up @@ -575,14 +591,14 @@ def singleton[TSource](value: TSource) -> TypedArray[TSource]:
return TypedArray((value,))


def sum[TSourceSum: SupportsSum](source: TypedArray[TSourceSum]) -> int:
def sum[TSourceSum: SupportsSum](source: TypedArray[TSourceSum]) -> TSourceSum | Literal[0]:
return builtins.sum(source.value)


@curry_flip(1)
def sum_by[TSource, TSourceSum: SupportsSum](
source: TypedArray[TSource], projection: Callable[[TSource], TSourceSum]
) -> int:
) -> TSourceSum | Literal[0]:
return builtins.sum(source.map(projection).value)


Expand Down
4 changes: 2 additions & 2 deletions expression/collections/asyncseq.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ def __init__(self, ai: AsyncIterable[TSource]):
async def map[TResult](self, mapper: Callable[[TSource], TResult]) -> "AsyncSeq[TResult]":
# Use the module-level `map` function defined later to transform the
# underlying async iterable and wrap the result back into an AsyncSeq.
return AsyncSeq(pipe(self._ai, map(mapper))) # type: ignore[arg-type]
return AsyncSeq(pipe(self._ai, map(mapper)))

@classmethod
def empty(cls) -> "AsyncSeq[Any]":
Expand Down Expand Up @@ -279,7 +279,7 @@ async def _filter(source: AsyncIterable[TSource]) -> AsyncIterable[TSource]:
return _filter


def map[TResult, TSource](
def map[TSource, TResult](
mapper: Callable[[TSource], TResult],
) -> Callable[[AsyncIterable[TSource]], AsyncIterable[TResult]]:
async def _map(source: AsyncIterable[TSource]) -> AsyncIterable[TResult]:
Expand Down
20 changes: 9 additions & 11 deletions expression/collections/block.py
Original file line number Diff line number Diff line change
Expand Up @@ -261,9 +261,7 @@ def starmap[*P, TResult](self: Block[tuple[*P]], mapping: Callable[[Unpack[P]],
def sum[TSourceSum: SupportsSum](self: Block[TSourceSum | Literal[0]]) -> TSourceSum | Literal[0]:
return builtins.sum(self._value)

def sum_by[TSourceSum: SupportsSum, TResult](
self: Block[TSourceSum], projection: Callable[[TSourceSum], TResult]
) -> TResult:
def sum_by[TResult: SupportsSum](self, projection: Callable[[_TSource], TResult]) -> TResult | Literal[0]:
return pipe(self, sum_by(projection))

def mapi[TResult](self, mapping: Callable[[int, _TSource], TResult]) -> Block[TResult]:
Expand Down Expand Up @@ -462,7 +460,7 @@ def try_head(self) -> Option[_TSource]:
return NOTHING

@staticmethod
def unfold[TResult, TState](
def unfold[TState, TResult](
generator: Callable[[TState], Option[tuple[TResult, TState]]], state: TState
) -> Block[TResult]:
"""Unfold block.
Expand Down Expand Up @@ -759,7 +757,7 @@ def reduce[TSource](
return source.tail().fold(reduction, source.head())


def starmap[TResult, *P](mapper: Callable[[Unpack[P]], TResult]) -> Callable[[Block[tuple[*P]]], Block[TResult]]:
def starmap[*P, TResult](mapper: Callable[[Unpack[P]], TResult]) -> Callable[[Block[tuple[*P]]], Block[TResult]]:
"""Starmap source sequence.

Unpack arguments grouped as tuple elements. Builds a new collection
Expand All @@ -779,13 +777,13 @@ def mapper_(args: tuple[*P]) -> TResult:
return map(mapper_)


def map2[TResult, T1, T2](
def map2[T1, T2, TResult](
mapper: Callable[[T1, T2], TResult],
) -> Callable[[Block[tuple[T1, T2]]], Block[TResult]]:
return starmap(mapper)


def map3[TResult, T1, T2, T3](
def map3[T1, T2, T3, TResult](
mapper: Callable[[T1, T2, T3], TResult],
) -> Callable[[Block[tuple[T1, T2, T3]]], Block[TResult]]:
return starmap(mapper)
Expand Down Expand Up @@ -937,11 +935,11 @@ def sum[TSourceSum: SupportsSum](source: Block[TSourceSum | Literal[0]]) -> TSou


@curry_flip(1)
def sum_by[TSourceSum: SupportsSum, TResult](
source: Block[TSourceSum], projection: Callable[[TSourceSum], TResult]
) -> TResult:
def sum_by[TSource, TResult: SupportsSum](
source: Block[TSource], projection: Callable[[TSource], TResult]
) -> TResult | Literal[0]:
xs = source.map(projection)
return builtins.sum(xs) # type: ignore
return builtins.sum(xs)


def tail[TSource](source: Block[TSource]) -> Block[TSource]:
Expand Down
27 changes: 14 additions & 13 deletions expression/collections/seq.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
import functools
import itertools
from collections.abc import Callable, Iterable, Iterator
from typing import TYPE_CHECKING, Any, cast, overload
from typing import TYPE_CHECKING, Any, Literal, cast, overload

from expression.core import (
NOTHING,
Expand Down Expand Up @@ -281,11 +281,13 @@ def skip(self, count: int) -> Seq[TSource]:
"""
return Seq(pipe(self, skip(count)))

def sum[TSupportsSum: SupportsSum](self: Seq[TSupportsSum]) -> TSupportsSum:
def sum[TSupportsSum: SupportsSum](self: Seq[TSupportsSum]) -> TSupportsSum | Literal[0]:
"""Returns the sum of the elements in the sequence."""
return sum(self)

def sum_by[TSupportsSum: SupportsSum](self, projection: Callable[[TSource], TSupportsSum]) -> TSupportsSum:
def sum_by[TSupportsSum: SupportsSum](
self, projection: Callable[[TSource], TSupportsSum]
) -> TSupportsSum | Literal[0]:
"""Sum the sequence by projection.

Returns the sum of the results generated by applying the
Expand Down Expand Up @@ -346,7 +348,7 @@ def to_obj(value: Any) -> Any:
return (to_obj(value) for value in self)

@classmethod
def unfold[TResult, TState](
def unfold[TState, TResult](
cls,
generator: Callable[[TState], Option[tuple[TResult, TState]]],
state: TState,
Expand Down Expand Up @@ -700,19 +702,19 @@ def gen():


@overload
def starmap[TResult, T1, T2](
def starmap[T1, T2, TResult](
mapper: Callable[[T1, T2], TResult],
) -> Callable[[Iterable[tuple[T1, T2]]], Iterable[TResult]]: ...


@overload
def starmap[TResult, T1, T2, T3](
def starmap[T1, T2, T3, TResult](
mapper: Callable[[T1, T2, T3], TResult],
) -> Callable[[Iterable[tuple[T1, T2, T3]]], Iterable[TResult]]: ...


@overload
def starmap[TResult, T1, T2, T3, T4](
def starmap[T1, T2, T3, T4, TResult](
mapper: Callable[[T1, T2, T3, T4], TResult],
) -> Callable[[Iterable[tuple[T1, T2, T3, T4]]], Iterable[TResult]]: ...

Expand All @@ -737,13 +739,13 @@ def mapper_(args: tuple[Any, ...]) -> Any:
return map(mapper_)


def map2[TResult, T1, T2](
def map2[T1, T2, TResult](
mapper: Callable[[T1, T2], TResult],
) -> Callable[[Iterable[tuple[T1, T2]]], Iterable[TResult]]:
return starmap(mapper)


def map3[TResult, T1, T2, T3](
def map3[T1, T2, T3, TResult](
mapper: Callable[[T1, T2, T3], TResult],
) -> Callable[[Iterable[tuple[T1, T2, T3]]], Iterable[TResult]]:
return starmap(mapper)
Expand Down Expand Up @@ -908,16 +910,15 @@ def gen():
return SeqGen(gen)


def sum[TSupportsSum: SupportsSum](source: Iterable[TSupportsSum]) -> TSupportsSum:
def sum[TSupportsSum: SupportsSum](source: Iterable[TSupportsSum]) -> TSupportsSum | Literal[0]:
"""Returns the sum of the elements in the sequence."""
ret = builtins.sum(source)
return cast(TSupportsSum, ret)
return builtins.sum(source)


@curry_flip(1)
def sum_by[TSource, TSupportsSum: SupportsSum](
source: Iterable[TSource], projection: Callable[[TSource], TSupportsSum]
) -> TSupportsSum:
) -> TSupportsSum | Literal[0]:
"""Sum all elements in sequence.

Returns the sum of the results generated by applying the function to
Expand Down
4 changes: 2 additions & 2 deletions expression/core/aiotools.py
Original file line number Diff line number Diff line change
Expand Up @@ -99,12 +99,12 @@ def cleanup(completed: Task[TSource]) -> None:
return task


def start(computation: Awaitable[Any], token: CancellationToken | None = None) -> None:
def start(computation: Awaitable[object], token: CancellationToken | None = None) -> None:
"""Schedule a computation on the running event loop."""
_start_task(computation, token)


def start_immediate(computation: Awaitable[Any], token: CancellationToken | None = None) -> None:
def start_immediate(computation: Awaitable[object], token: CancellationToken | None = None) -> None:
"""Schedule a computation on the running event loop.

Execution begins when the event loop next runs the task.
Expand Down
9 changes: 4 additions & 5 deletions expression/core/misc.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
from collections.abc import Callable
from typing import Any


def identity[A](value: A) -> A:
Expand All @@ -14,26 +13,26 @@ def starid[*P](*value: *P) -> tuple[*P]:
return value


def flip[TResult, A, B](fn: Callable[[A, B], TResult]) -> Callable[[B, A], TResult]:
def flip[A, B, TResult](fn: Callable[[A, B], TResult]) -> Callable[[B, A], TResult]:
"""Flips the arguments for a function taking two arguments.

Example:
>>> fn(a, b) == flip(fn)(b, a)
"""

def _flip(b: B, a: A) -> Any:
def _flip(b: B, a: A) -> TResult:
return fn(a, b)

return _flip


def snd[TSource](value: tuple[Any, TSource]) -> TSource:
def snd[TSource](value: tuple[object, TSource]) -> TSource:
"""Return second argument of the tuple."""
_, b = value
return b


def fst[TSource](value: tuple[TSource, Any]) -> TSource:
def fst[TSource](value: tuple[TSource, object]) -> TSource:
"""Return first argument of the tuple."""
a, _ = value
return a
Expand Down
6 changes: 3 additions & 3 deletions expression/core/option.py
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ def map[TResult](self, mapper: Callable[[_TSourceOut], TResult]) -> Some[TResult
"""Transform the present value."""
return Some(mapper(self.some))

def map2[TResult, T2](self, mapper: Callable[[_TSourceOut, T2], TResult], other: Option[T2]) -> Option[TResult]:
def map2[T2, TResult](self, mapper: Callable[[_TSourceOut, T2], TResult], other: Option[T2]) -> Option[TResult]:
"""Transform two present values, or return Nothing."""
return other.map(lambda value: mapper(self.some, value))

Expand Down Expand Up @@ -339,12 +339,12 @@ def apply(function: Nothing) -> Callable[[Option[object]], Nothing]: ...


@overload
def apply[TResult, TSource](
def apply[TSource, TResult](
function: Option[Callable[[TSource], TResult]],
) -> Callable[[Option[TSource]], Option[TResult]]: ...


def apply[TResult, TSource](
def apply[TSource, TResult](
function: Option[Callable[[TSource], TResult]],
) -> Callable[[Option[TSource]], Option[TResult]]:
"""Apply an optional function to an optional value."""
Expand Down
Loading
Loading