diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index 6f93bed4..ba04a7f3 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -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 diff --git a/Justfile b/Justfile index 64207858..3704fa9d 100644 --- a/Justfile +++ b/Justfile @@ -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: diff --git a/README.md b/README.md index 3c8c6c70..a8e97837 100644 --- a/README.md +++ b/README.md @@ -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] diff --git a/README.py b/README.py index a6e0bf4e..2fe802cb 100644 --- a/README.py +++ b/README.py @@ -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] diff --git a/TAGGED_UNION_PROPOSAL.md b/TAGGED_UNION_PROPOSAL.md index e1486f2f..468e1929 100644 --- a/TAGGED_UNION_PROPOSAL.md +++ b/TAGGED_UNION_PROPOSAL.md @@ -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 @@ -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), diff --git a/docs/contributing.md b/docs/contributing.md index 519d6125..eb1f92b7 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -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 diff --git a/docs/guides/effects.py b/docs/guides/effects.py index 5761bd90..ffe52925 100644 --- a/docs/guides/effects.py +++ b/docs/guides/effects.py @@ -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.") @@ -32,7 +30,7 @@ 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) @@ -40,7 +38,7 @@ def maybe_add(left: Option[int], right: Option[int]) -> Generator[int, int, int] # %% [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. """ diff --git a/docs/guides/migration-major.md b/docs/guides/migration-major.md index 57b3936b..6e06a0c9 100644 --- a/docs/guides/migration-major.md +++ b/docs/guides/migration-major.md @@ -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. diff --git a/docs/guides/pipelines.py b/docs/guides/pipelines.py index 1b3632f2..c7c4664a 100644 --- a/docs/guides/pipelines.py +++ b/docs/guides/pipelines.py @@ -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}, @@ -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, ) @@ -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, ) diff --git a/docs/reference/union.md b/docs/reference/union.md index 591bd968..b8b10d37 100644 --- a/docs/reference/union.md +++ b/docs/reference/union.md @@ -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 diff --git a/docs/tutorial/continuations.py b/docs/tutorial/continuations.py index 8b94d74d..88ad1078 100644 --- a/docs/tutorial/continuations.py +++ b/docs/tutorial/continuations.py @@ -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] """ diff --git a/docs/tutorial/effects.py b/docs/tutorial/effects.py index a344659a..08dd9586 100644 --- a/docs/tutorial/effects.py +++ b/docs/tutorial/effects.py @@ -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) @@ -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. diff --git a/docs/tutorial/introduction.py b/docs/tutorial/introduction.py index 517fa19f..5c2fc82b 100644 --- a/docs/tutorial/introduction.py +++ b/docs/tutorial/introduction.py @@ -10,6 +10,8 @@ """ # %% +from collections.abc import Mapping + from expression import pipe from expression.collections import seq @@ -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"]) diff --git a/expression/collections/array.py b/expression/collections/array.py index f20b34a0..426a28b0 100644 --- a/expression/collections/array.py +++ b/expression/collections/array.py @@ -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,)) @@ -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 diff --git a/expression/collections/block.py b/expression/collections/block.py index 8d1b358d..fbea001e 100644 --- a/expression/collections/block.py +++ b/expression/collections/block.py @@ -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,)) @@ -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]]: @@ -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]: @@ -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 diff --git a/expression/collections/map.py b/expression/collections/map.py index 93464ff2..c2498866 100644 --- a/expression/collections/map.py +++ b/expression/collections/map.py @@ -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: @@ -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: diff --git a/expression/collections/seq.py b/expression/collections/seq.py index fe68febe..d5492148 100644 --- a/expression/collections/seq.py +++ b/expression/collections/seq.py @@ -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]: @@ -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 @@ -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 diff --git a/pyproject.toml b/pyproject.toml index c0216335..6bfd1c60 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" diff --git a/pyrightconfig.json b/pyrightconfig.json index 4dcff005..3c0dfd0c 100644 --- a/pyrightconfig.json +++ b/pyrightconfig.json @@ -1,9 +1,11 @@ { "include": [ "expression", + "scripts", "tests", "README.py", - "docs/guides/getting-started.py" + "docs/guides", + "docs/tutorial" ], "reportImportCycles": false, "reportMissingImports": false, diff --git a/scripts/check_docs.py b/scripts/check_docs.py new file mode 100644 index 00000000..d2aa4851 --- /dev/null +++ b/scripts/check_docs.py @@ -0,0 +1,38 @@ +"""Execute documentation examples, including notebook cells with top-level await.""" + +import ast +import asyncio +import inspect +import subprocess +import sys +from pathlib import Path + + +async def run_example(path: Path) -> None: + """Run a guide in a notebook-compatible event loop and namespace.""" + code = compile(path.read_text(), str(path), "exec", flags=ast.PyCF_ALLOW_TOP_LEVEL_AWAIT) + namespace = {"__name__": "__main__", "__file__": str(path)} + result = eval(code, namespace) + if inspect.isawaitable(result): + await result + + +def main() -> int: + """Run each document in a fresh process so examples cannot share state.""" + if len(sys.argv) == 2: + asyncio.run(run_example(Path(sys.argv[1]))) + return 0 + + root = Path(__file__).resolve().parent.parent + examples = sorted((root / "docs/guides").glob("*.py")) + sorted((root / "docs/tutorial").glob("*.py")) + for path in examples: + result = subprocess.run([sys.executable, __file__, str(path)], cwd=root, check=False, timeout=60) + if result.returncode: + sys.stderr.write(f"Documentation example failed: {path.relative_to(root)}\n") + return result.returncode + sys.stdout.write(f"Executed {len(examples)} documentation examples.\n") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_seq.py b/tests/test_seq.py index 478ba7fe..7691b494 100644 --- a/tests/test_seq.py +++ b/tests/test_seq.py @@ -567,3 +567,12 @@ def test_seq_monad_law_associativity_empty(value: int): # Empty list m = empty assert list(m.collect(f).collect(g)) == list(m.collect(lambda x: f(x).collect(g))) + + +def test_of_iterable_preserves_subclass(): + class IntSeq(Seq[int]): + pass + + values = IntSeq.of_iterable([1, 2, 3]) + assert isinstance(values, IntSeq) + assert list(values) == [1, 2, 3] diff --git a/tests/typing_contracts.py b/tests/typing_contracts.py index 946a8c9b..f1848dd1 100644 --- a/tests/typing_contracts.py +++ b/tests/typing_contracts.py @@ -2,7 +2,7 @@ from __future__ import annotations -from collections.abc import Generator +from collections.abc import Generator, Iterable from dataclasses import field from typing import Generic, Literal, TypeAlias, TypeVar, assert_never, assert_type, cast, final @@ -21,6 +21,28 @@ result, tag, ) +from expression.collections import Block, Map, Seq, TypedArray + + +def collection_factory_contract() -> None: + assert_type(Block.of("a", "b"), Block[str]) + assert_type(Block.singleton(42), Block[int]) + assert_type(Block.of_option(Some(42)), Block[int]) + assert_type(TypedArray.of(1, 2), TypedArray[int]) + assert_type(TypedArray.of_seq([1, 2]), TypedArray[int]) + pairs: list[tuple[str, int]] = [("a", 1)] + assert_type(Map.create(pairs), Map[str, int]) + entries: Block[tuple[str, int]] = Block.of(("a", 1)) + assert_type(Map.of_block(entries), Map[str, int]) + assert_type(Seq.delay(lambda: [1, 2]), Iterable[int]) + assert_type(Seq.of_iterable([1, 2]), Seq[int]) + + def generate(state: int) -> Option[tuple[str, int]]: + return Some((str(state), state + 1)) if state < 3 else NOTHING + + assert_type(Block.unfold(generate, 0), Block[str]) + assert_type(TypedArray.unfold(generate, 0), TypedArray[str]) + assert_type(Seq.unfold(generate, 0), Iterable[str]) def option_contract(value: Option[int]) -> None: diff --git a/typing_tests/negative.py b/typing_tests/negative.py index 2ea48a18..c236dc37 100644 --- a/typing_tests/negative.py +++ b/typing_tests/negative.py @@ -4,6 +4,7 @@ from typing import Generic, Literal, TypeAlias, TypeVar, final from expression import Error, MailboxProcessor, Nothing, Option, Result, Some, TaggedUnion, apipe, case, tag +from expression.collections import Block, Map, TypedArray from expression.extra import async_result @@ -29,6 +30,9 @@ def wrong_case(value: Option[int]) -> None: wrong_payload: Option[int] = Some("wrong") # type-error wrong_error_payload: Result[int, str] = Error(42) # type-error +wrong_block_items: Block[int] = Block.of("wrong") # type-error +wrong_array_items: TypedArray[int] = TypedArray.of("wrong") # type-error +wrong_map_values: Map[str, int] = Map.create([("key", "wrong")]) # type-error missing_payload = Some() # type-error contradictory_tag = Some(1, tag="none") # type-error diff --git a/uv.lock b/uv.lock index 91ca10d5..8ac782be 100644 --- a/uv.lock +++ b/uv.lock @@ -351,8 +351,8 @@ dev = [ [package.metadata] requires-dist = [ - { name = "pydantic", marker = "extra == 'all'", specifier = ">=2.10.0,<3.0.0" }, - { name = "pydantic", marker = "extra == 'pydantic'", specifier = ">=2.10.0,<3.0.0" }, + { name = "pydantic", marker = "extra == 'all'", specifier = ">=2.11.0,<3.0.0" }, + { name = "pydantic", marker = "extra == 'pydantic'", specifier = ">=2.11.0,<3.0.0" }, { name = "typing-extensions", specifier = ">=4.6.0" }, ] provides-extras = ["all", "pydantic"]