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
35 changes: 35 additions & 0 deletions .github/workflows/python-package.yml
Original file line number Diff line number Diff line change
Expand Up @@ -49,3 +49,38 @@ jobs:

- name: Test with pytest
run: uv run pytest

- name: Run documentation examples
run: uv run python scripts/check_docs.py

minimum-dependencies:
name: Python 3.12 minimum dependencies
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7

- uses: actions/setup-python@v7
with:
python-version: "3.12"

- uses: astral-sh/setup-uv@v7

- name: Build and install wheel without optional dependencies
run: |
uv build
uv venv "$RUNNER_TEMP/minimum-venv"
uv pip install --python "$RUNNER_TEMP/minimum-venv/bin/python" dist/*.whl 'typing-extensions==4.6.0'
cd "$RUNNER_TEMP"
"$RUNNER_TEMP/minimum-venv/bin/python" -c 'from expression import Some; assert Some(1).map(str) == Some("1")'

- name: Install minimum Pydantic and test dependencies
run: |
uv pip install --python "$RUNNER_TEMP/minimum-venv/bin/python" 'pydantic==2.11.0' 'typing-extensions==4.12.2' pytest pytest-asyncio hypothesis

- name: Test the installed wheel outside the checkout
run: |
mkdir "$RUNNER_TEMP/wheel-tests"
cp -r tests "$RUNNER_TEMP/wheel-tests/tests"
cp pyproject.toml "$RUNNER_TEMP/wheel-tests/pyproject.toml"
cd "$RUNNER_TEMP/wheel-tests"
"$RUNNER_TEMP/minimum-venv/bin/python" -m pytest
1 change: 1 addition & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ install:
# Run the complete test suite.
test:
uv run pytest
uv run python scripts/check_docs.py

# Run all formatting, linting, type-checking, and repository checks.
lint:
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ You can install the latest `expression` from PyPI by running `pip` (or
> pip install expression
```

To add Pydantic 2.10+ support, install the `pydantic` extra:
To add Pydantic 2.11+ support, install the `pydantic` extra:

```console
> pip install expression[pydantic]
Expand Down
2 changes: 1 addition & 1 deletion README.py
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@
> pip install expression
```

To add Pydantic 2.10+ support, install the `pydantic` extra:
To add Pydantic 2.11+ support, install the `pydantic` extra:

```console
> pip install expression[pydantic]
Expand Down
9 changes: 4 additions & 5 deletions TAGGED_UNION_PROPOSAL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Tagged unions: implementation and rationale

**Status:** Implemented for the next major version of Expression.
**Minimum Python:** 3.12. **Optional Pydantic:** 2.10 or later, below 3.
**Minimum Python:** 3.12. **Optional Pydantic:** 2.11 or later, below 3.

Expression now represents tagged unions as explicit, frozen, final case classes
combined in public type aliases. Each case declares only its own payload. The
Expand Down Expand Up @@ -327,10 +327,9 @@ payloads; arbitrary leaf encoding remains the caller's responsibility. Custom
cases retain ordinary dataclass facilities such as `asdict` rather than gaining
a built-in `.dict()` method.

Pydantic is optional. The minimum is 2.10.0 because earlier versions could resolve
Expression's deferred generic annotations against caller-local type variables,
silently losing payload validation. A repository regression covers that name
collision. Old raw/null Option data requires explicit migration; no legacy codec
Pydantic is optional. The minimum is 2.11.0 to support cases declared with
Python 3.12 type parameters. Repository regressions cover nested generic
payload validation and collisions with caller-local type-variable names. Old raw/null Option data requires explicit migration; no legacy codec
is included.

Source: [schema construction](expression/core/_union_schema.py),
Expand Down
3 changes: 3 additions & 0 deletions docs/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ public feature changes.

- Add or update a task-focused example for changed user-visible behavior.
- Keep code examples compatible with supported Python versions and public APIs.
- Run `just lint` to type-check the guides and tutorials, and `just test` to run
their assertions alongside the library tests. The example runner supports notebook
cells with top-level `await` and executes each document in a separate process.
- Explain unfamiliar terms in plain language before using their technical name.
- Link a guide to the detailed API reference and vice versa.
- Update `README.py`, then run `uv run ./make_readme.sh`, when the project overview or
Expand Down
10 changes: 4 additions & 6 deletions docs/guides/effects.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,8 @@ def parse_count(value: str) -> Result[int, str]:
return Ok(int(value)) if value.isdigit() else Error("Count must be numeric.")

@effect.result[int, str]()
def total(left: str, right: str) -> Generator[int, int, int]:
first = yield from parse_count(left)
second = yield from parse_count(right)
return first + second
def total(left: str, right: str) -> Generator[int, None, None]:
yield from (first + second for first in parse_count(left) for second in parse_count(right))

assert total("2", "3") == Ok(5)
assert total("2", "three") == Error("Count must be numeric.")
Expand All @@ -32,15 +30,15 @@ def total(left: str, right: str) -> Generator[int, int, int]:
"""
# %%
@effect.option[int]()
def maybe_add(left: Option[int], right: Option[int]) -> Generator[int, int, int]:
def maybe_add(left: Option[int], right: Option[int]) -> Generator[int, None, None]:
yield from (left_value + right_value for left_value in left for right_value in right)

assert maybe_add(Some(2), Some(3)) == Some(5)
assert maybe_add(Some(2), NOTHING) == NOTHING

# %% [markdown]
"""
When any yielded `Result` is an `Error`, the remaining statements are skipped. The
When a `Result` step is an `Error`, the remaining steps are skipped. The
library also provides `option`, `seq`, `async_option`, `async_result`, and `async_try`
builders. Use the [effects overview](../reference/effects) to choose one.
"""
4 changes: 2 additions & 2 deletions docs/guides/migration-major.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Migrating to case unions

This major version requires Python 3.12 or later. The optional Pydantic
integration requires Pydantic 2.10 or later to preserve generic payload
validation when caller and library type-variable names overlap.
integration requires Pydantic 2.11 or later to validate cases declared with
Python 3.12 type parameters, including nested generic payloads.

Expression supports at least the latest three stable Python versions. Minimum
Python versions are raised in major releases; this release supports 3.12–3.15.
Expand Down
13 changes: 9 additions & 4 deletions docs/guides/pipelines.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,17 @@
step receives the previous result, so the order reads from top to bottom.
"""
# %%
from collections.abc import Mapping

from expression import pipe
from expression.collections import seq

def is_active(user: dict[str, object]) -> bool:
def is_active(user: Mapping[str, str | bool]) -> bool:
return user["active"] is True

def name(user: Mapping[str, str | bool]) -> str:
return str(user["name"])

users = [
{"name": "Ada", "active": True},
{"name": "Grace", "active": False},
Expand All @@ -21,7 +26,7 @@ def is_active(user: dict[str, object]) -> bool:
names = pipe(
users,
seq.filter(is_active),
seq.map(lambda user: str(user["name"])),
seq.map(name),
list,
)

Expand All @@ -42,8 +47,8 @@ def is_active(user: dict[str, object]) -> bool:
from expression.collections import seq

active_names = compose(
seq.filter(lambda user: user["active"] is True),
seq.map(lambda user: str(user["name"])),
seq.filter(is_active),
seq.map(name),
list,
)

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/union.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ payloads, standard Python enums are usually sufficient.
## Tagged serialization

`dataclasses.asdict(Circle(2.0))` returns `{"radius": 2.0, "tag": "circle"}`.
With the optional Pydantic extra (Pydantic 2.10+), use the public alias at decoding
With the optional Pydantic extra (Pydantic 2.11+), use the public alias at decoding
boundaries:

```python
Expand Down
2 changes: 1 addition & 1 deletion docs/tutorial/continuations.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ async def check_load_count() -> None:
assert await load_count_async() == 42


await check_load_count() # noqa: F704 - valid top-level await in a Jupyter cell
await check_load_count() # type: ignore # noqa: F704 - Jupyter cell

# %% [markdown]
"""
Expand Down
22 changes: 19 additions & 3 deletions docs/tutorial/effects.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,23 @@ def apply_discount(price: int, percentage: int) -> Result[int, str]:
return Ok(price * (100 - percentage) // 100)


# Preferred direct-style version; restore this when Pyright fixes its known
# yield-from return-type inference bug for unions such as Result (Ok | Error).
# The original works at runtime; the comprehension below is a typing workaround.
#
# @effect.result[int, str]()
# def discounted_price(raw_price: str, percentage: int) -> Generator[int, int, int]:
# price = yield from parse_price(raw_price)
# return (yield from apply_discount(price, percentage))


@effect.result[int, str]()
def discounted_price(raw_price: str, percentage: int) -> Generator[int, int, int]:
price = yield from parse_price(raw_price)
return (yield from apply_discount(price, percentage))
def discounted_price(raw_price: str, percentage: int) -> Generator[int, None, None]:
yield from (
discounted
for price in parse_price(raw_price)
for discounted in apply_discount(price, percentage)
)


assert discounted_price("120", 25) == Ok(90)
Expand All @@ -35,6 +48,9 @@ def discounted_price(raw_price: str, percentage: int) -> Generator[int, int, int

# %% [markdown]
"""
Generator comprehensions keep each binding typed independently. Iterating an
`Error` short-circuits the builder before subsequent steps run.

The `option`, `seq`, `async_option`, `async_result`, and `async_try` builders follow the
same idea for their respective return types. Use a builder only when it makes a workflow
clearer than a chain of `bind` calls.
Expand Down
6 changes: 4 additions & 2 deletions docs/tutorial/introduction.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@
"""

# %%
from collections.abc import Mapping

from expression import pipe
from expression.collections import seq

Expand All @@ -20,11 +22,11 @@
]


def is_paid(order: dict[str, object]) -> bool:
def is_paid(order: Mapping[str, str | int | bool]) -> bool:
return order["paid"] is True


def amount(order: dict[str, object]) -> int:
def amount(order: Mapping[str, str | int | bool]) -> int:
return int(order["amount"])


Expand Down
10 changes: 5 additions & 5 deletions expression/collections/array.py
Original file line number Diff line number Diff line change
Expand Up @@ -312,12 +312,12 @@ def item(self, index: int) -> TSource:
return self.value[index]

@staticmethod
def of(*args: TSource) -> TypedArray[TSource]:
def of[TResult](*args: TResult) -> TypedArray[TResult]:
"""Create list from a number of arguments."""
return TypedArray((*args,))

@staticmethod
def of_seq(xs: Iterable[TSource]) -> TypedArray[TSource]:
def of_seq[TResult](xs: Iterable[TResult]) -> TypedArray[TResult]:
"""Create list from iterable sequence."""
return TypedArray((*xs,))

Expand Down Expand Up @@ -416,9 +416,9 @@ def try_head(self) -> Option[TSource]:
return NOTHING

@staticmethod
def unfold[TState](
generator: Callable[[TState], Option[tuple[TSource, TState]]], state: TState
) -> TypedArray[TSource]:
def unfold[TResult, TState](
generator: Callable[[TState], Option[tuple[TResult, TState]]], state: TState
) -> TypedArray[TResult]:
"""Unfold array.

Returns a list that contains the elements generated by the
Expand Down
12 changes: 6 additions & 6 deletions expression/collections/block.py
Original file line number Diff line number Diff line change
Expand Up @@ -284,7 +284,7 @@ def mapi[TResult](self, mapping: Callable[[int, _TSource], TResult]) -> Block[TR
return Block((*itertools.starmap(mapping, enumerate(self)),))

@staticmethod
def of(*args: _TSource) -> Block[_TSource]:
def of[TResult](*args: TResult) -> Block[TResult]:
"""Create list from a number of arguments."""
return Block((*args,))

Expand All @@ -294,7 +294,7 @@ def of_seq[TResult](xs: Iterable[TResult]) -> Block[TResult]:
return Block((*xs,))

@staticmethod
def of_option(option: Option[_TSource]) -> Block[_TSource]:
def of_option[TResult](option: Option[TResult]) -> Block[TResult]:
return of_option(option)

def partition(self, predicate: Callable[[_TSource], bool]) -> tuple[Block[_TSource], Block[_TSource]]:
Expand Down Expand Up @@ -362,7 +362,7 @@ def reduce(
return reduce(reduction)(self)

@staticmethod
def singleton(item: _TSource) -> Block[_TSource]:
def singleton[TResult](item: TResult) -> Block[TResult]:
return singleton(item)

def skip(self, count: int) -> Block[_TSource]:
Expand Down Expand Up @@ -462,9 +462,9 @@ def try_head(self) -> Option[_TSource]:
return NOTHING

@staticmethod
def unfold[TState](
generator: Callable[[TState], Option[tuple[_TSource, TState]]], state: TState
) -> Block[_TSource]:
def unfold[TResult, TState](
generator: Callable[[TState], Option[tuple[TResult, TState]]], state: TState
) -> Block[TResult]:
"""Unfold block.

Returns a list that contains the elements generated by the
Expand Down
4 changes: 2 additions & 2 deletions expression/collections/map.py
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ def add(self, key: _Key, value: _Value) -> Map[_Key, _Value]:
return Map(maptree.add(key, value, self._tree))

@staticmethod
def create(ie: Iterable[tuple[_Key, _Value]]) -> Map[_Key, _Value]:
def create[TKey: SupportsLessThanAndHash, TValue](ie: Iterable[tuple[TKey, TValue]]) -> Map[TKey, TValue]:
return create(ie)

def contains_key(self, key: _Key) -> bool:
Expand Down Expand Up @@ -166,7 +166,7 @@ def of[Result](**args: Result) -> Map[str, Result]:
return Map(maptree.of_seq(args.items()))

@staticmethod
def of_block(lst: Block[tuple[_Key, _Value]]) -> Map[_Key, _Value]:
def of_block[TKey: SupportsLessThanAndHash, TValue](lst: Block[tuple[TKey, TValue]]) -> Map[TKey, TValue]:
"""Generate map from list.

Returns:
Expand Down
10 changes: 5 additions & 5 deletions expression/collections/seq.py
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ def of[TResult](*args: TResult) -> Seq[TResult]:
return Seq(args)

@classmethod
def of_iterable(cls, source: Iterable[TSource]) -> Seq[TSource]:
def of_iterable[TResult](cls: type[Seq[Any]], source: Iterable[TResult]) -> Seq[TResult]:
return cls(source)

def append(self, *others: Iterable[TSource]) -> Seq[TSource]:
Expand Down Expand Up @@ -125,7 +125,7 @@ def collect[TResult](self, mapping: Callable[[TSource], Seq[TResult]]) -> Seq[TR
return self.map(mapping).concat()

@staticmethod
def delay(generator: Callable[[], Iterable[TSource]]) -> Iterable[TSource]:
def delay[TResult](generator: Callable[[], Iterable[TResult]]) -> Iterable[TResult]:
"""Delay sequence.

Returns a sequence that is built from the given delayed specification of a
Expand Down Expand Up @@ -346,11 +346,11 @@ def to_obj(value: Any) -> Any:
return (to_obj(value) for value in self)

@classmethod
def unfold[TState](
def unfold[TResult, TState](
cls,
generator: Callable[[TState], Option[tuple[TSource, TState]]],
generator: Callable[[TState], Option[tuple[TResult, TState]]],
state: TState,
) -> Iterable[TSource]:
) -> Iterable[TResult]:
"""Unfold sequence.

Returns a list that contains the elements generated by the
Expand Down
4 changes: 2 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ dependencies = [
]

[project.optional-dependencies]
pydantic = ["pydantic>=2.10.0,<3.0.0"]
all = ["pydantic>=2.10.0,<3.0.0"]
pydantic = ["pydantic>=2.11.0,<3.0.0"]
all = ["pydantic>=2.11.0,<3.0.0"]

[project.urls]
Homepage = "https://github.com/cognitedata/Expression"
Expand Down
4 changes: 3 additions & 1 deletion pyrightconfig.json
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
{
"include": [
"expression",
"scripts",
"tests",
"README.py",
"docs/guides/getting-started.py"
"docs/guides",
"docs/tutorial"
],
"reportImportCycles": false,
"reportMissingImports": false,
Expand Down
Loading
Loading