From 239eb9b928af1e1ce456d34ceeeb161f0acab695 Mon Sep 17 00:00:00 2001 From: dhairya05 Date: Fri, 6 Nov 2026 21:51:46 +0530 Subject: [PATCH 1/4] [behave] Add stubs for model.Table and model.Row MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `behave.model` had no stubs at all, so `context.table` — the object almost every step implementation that uses a Gherkin data table touches — was `Incomplete`, and everything reached through it was `Any`. Adds `behave/model.pyi` covering `Table` and `Row`, and `behave/model_core.pyi` covering `Replayable`, which `Table` derives from. Both modules keep the module-level `__getattr__` escape hatch, so the rest of `behave.model` is unaffected and the package stays a partial stub. `Context` is wired up to the new types: - `table: Table | None`, assigned from `Step.table` in `Step.run`, and None at root - `active_outline: Row | None`, assigned from `scenario._row` in `ScenarioOutline.run` and reset to None afterwards Signatures were read off behave 1.3.3 and checked at runtime, including the cases that needed care: - `Table.__getitem__` is overloaded, since `table[0]` returns a `Row` while `table[0:2]` returns `list[Row]` - `Row.items()` returns a `zip` object, not a list or a view - `Row.as_dict()` returns an `OrderedDict` - `Row.get` is overloaded on its default, like `Mapping.get` - `Table.assert_equals` is `NoReturn`: it asserts, then unconditionally raises `NotImplementedError` - `Replayable.type` is `None` on the base class and a string on subclasses, so it is `ClassVar[str | None]` there and `ClassVar[str]` on `Table` - `Table.from_data` returns `Table` rather than `Self`, because one branch constructs `Table` directly instead of `cls` Verified with stubtest (84 modules, no issues) and `mypy --strict`: a representative step implementation that reads headings, iterates rows, and uses named, indexed and sliced access reported 14 `Any` errors before this change and none after. --- stubs/behave/behave/model.pyi | 76 ++++++++++++++++++++++++++++++ stubs/behave/behave/model_core.pyi | 8 ++++ stubs/behave/behave/runner.pyi | 6 ++- 3 files changed, 88 insertions(+), 2 deletions(-) create mode 100644 stubs/behave/behave/model.pyi create mode 100644 stubs/behave/behave/model_core.pyi diff --git a/stubs/behave/behave/model.pyi b/stubs/behave/behave/model.pyi new file mode 100644 index 000000000000..d3e72a56a29c --- /dev/null +++ b/stubs/behave/behave/model.pyi @@ -0,0 +1,76 @@ +from _typeshed import Incomplete +from collections import OrderedDict +from collections.abc import Iterable, Iterator, Mapping, Sequence +from typing import ClassVar, NoReturn, TypeAlias, TypeVar, overload +from typing_extensions import Self + +from behave.model_core import Replayable + +_T = TypeVar("_T") + +# A table row, either already parsed or as a plain list of cell values. +_RowData: TypeAlias = Row | list[str] + +class Table(Replayable): + type: ClassVar[str] + headings: list[str] + rows: list[Row] + line: int + modified: bool + def __init__(self, headings: list[str], rows: Iterable[_RowData] | None = None, line: int | None = None) -> None: ... + def clear(self, headings: list[str] | None = None, keep_headings: bool = True) -> None: ... + def add_row(self, row: _RowData, line: int | None = None) -> None: ... + def add_column(self, column_name: str, values: Iterable[str] | None = None, default_value: str = "") -> int: ... + def remove_column(self, column_name_or_index: str | int) -> None: ... + def remove_columns(self, column_names: Iterable[str]) -> None: ... + def has_column(self, column_name: str) -> bool: ... + def get_column_index(self, column_name: str) -> int: ... + def require_column(self, column_name: str) -> int: ... + def require_columns(self, column_names: Iterable[str]) -> None: ... + def ensure_column_exists(self, column_name: str) -> int: ... + def __eq__(self, other: object) -> bool: ... + def __ne__(self, other: object) -> bool: ... + def __iter__(self) -> Iterator[Row]: ... + + @overload + def __getitem__(self, index: int) -> Row: ... + @overload + def __getitem__(self, index: slice) -> list[Row]: ... + + # Always raises: the comparison is asserted and then `NotImplementedError` is raised. + def assert_equals(self, data: object) -> NoReturn: ... + @classmethod + def from_dicts(cls, headings: list[str], table_data: Sequence[Mapping[str, str]], line: int | None = None) -> Self: ... + @classmethod + def from_data( + cls, headings: list[str], table_data: Sequence[Mapping[str, str] | _RowData] | None = None, line: int = 0 + ) -> Table: ... + +class Row: + headings: list[str] + cells: list[str] + line: int | None + comments: Incomplete | None + def __init__( + self, headings: list[str], cells: list[str], line: int | None = None, comments: Incomplete | None = None + ) -> None: ... + def __getitem__(self, name: str | int) -> str: ... + def __contains__(self, item: str) -> bool: ... + def __eq__(self, other: object) -> bool: ... + def __ne__(self, other: object) -> bool: ... + def __len__(self) -> int: ... + def __iter__(self) -> Iterator[str]: ... + def items(self) -> zip[tuple[str, str]]: ... + + @overload + def get(self, key: str | int, default: None = None) -> str | None: ... + @overload + def get(self, key: str | int, default: _T) -> str | _T: ... + + def as_dict(self) -> OrderedDict[str, str]: ... + @classmethod + def from_dict( + cls, headings: list[str], row_data: Mapping[str, str], *, line: int | None = None, comments: Incomplete | None = None + ) -> Self: ... + +def __getattr__(name: str) -> Incomplete: ... diff --git a/stubs/behave/behave/model_core.pyi b/stubs/behave/behave/model_core.pyi new file mode 100644 index 000000000000..f2b1bc5d94d5 --- /dev/null +++ b/stubs/behave/behave/model_core.pyi @@ -0,0 +1,8 @@ +from _typeshed import Incomplete +from typing import ClassVar + +class Replayable: + type: ClassVar[str | None] + def replay(self, formatter) -> None: ... + +def __getattr__(name: str) -> Incomplete: ... diff --git a/stubs/behave/behave/runner.pyi b/stubs/behave/behave/runner.pyi index a3abfa2d0de2..c3d3e7f792f5 100644 --- a/stubs/behave/behave/runner.pyi +++ b/stubs/behave/behave/runner.pyi @@ -3,6 +3,8 @@ from collections.abc import Callable from contextlib import AbstractContextManager from typing import ClassVar, ParamSpec +from behave.model import Row, Table + _P = ParamSpec("_P") class Context: @@ -14,10 +16,10 @@ class Context: tags: set[str] aborted: bool failed: bool - table: Incomplete | None + table: Table | None text: str | None config: Incomplete - active_outline: Incomplete + active_outline: Row | None fail_on_cleanup_errors: bool def __init__(self, runner) -> None: ... From 577dc60ff96d60e5a89de51584fe62dd8aac1e4d Mon Sep 17 00:00:00 2001 From: dhairya05 Date: Mon, 9 Nov 2026 02:03:10 +0530 Subject: [PATCH 2/4] Use =None for the incomplete comments parameters flake8-pyi Y067: an argument whose type is unknown and defaults to None is written as comments=None rather than comments: Incomplete | None = None. The class attribute keeps its annotation. Black then fits both signatures on one line. --- stubs/behave/behave/model.pyi | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/stubs/behave/behave/model.pyi b/stubs/behave/behave/model.pyi index d3e72a56a29c..ccf0bddf2495 100644 --- a/stubs/behave/behave/model.pyi +++ b/stubs/behave/behave/model.pyi @@ -51,9 +51,7 @@ class Row: cells: list[str] line: int | None comments: Incomplete | None - def __init__( - self, headings: list[str], cells: list[str], line: int | None = None, comments: Incomplete | None = None - ) -> None: ... + def __init__(self, headings: list[str], cells: list[str], line: int | None = None, comments=None) -> None: ... def __getitem__(self, name: str | int) -> str: ... def __contains__(self, item: str) -> bool: ... def __eq__(self, other: object) -> bool: ... @@ -69,8 +67,6 @@ class Row: def as_dict(self) -> OrderedDict[str, str]: ... @classmethod - def from_dict( - cls, headings: list[str], row_data: Mapping[str, str], *, line: int | None = None, comments: Incomplete | None = None - ) -> Self: ... + def from_dict(cls, headings: list[str], row_data: Mapping[str, str], *, line: int | None = None, comments=None) -> Self: ... def __getattr__(name: str) -> Incomplete: ... From a2f1e416b9572938d187ea769edbfb967bd21d54 Mon Sep 17 00:00:00 2001 From: dhairya05 Date: Tue, 10 Nov 2026 14:16:21 +0530 Subject: [PATCH 3/4] [behave] Table.from_dicts/from_data take dicts, not any Mapping Both methods gate on isinstance(table_data[0], dict): from_dicts raises TypeError for a non-dict, and from_data silently takes the other branch and passes the data to Table(rows=...). A Mapping that is not a dict is not accepted by either, so annotate the element type as dict[str, str]. Row.from_dict keeps Mapping: it only calls row_data.get(name). --- stubs/behave/behave/model.pyi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stubs/behave/behave/model.pyi b/stubs/behave/behave/model.pyi index ccf0bddf2495..2156b43edff2 100644 --- a/stubs/behave/behave/model.pyi +++ b/stubs/behave/behave/model.pyi @@ -40,10 +40,10 @@ class Table(Replayable): # Always raises: the comparison is asserted and then `NotImplementedError` is raised. def assert_equals(self, data: object) -> NoReturn: ... @classmethod - def from_dicts(cls, headings: list[str], table_data: Sequence[Mapping[str, str]], line: int | None = None) -> Self: ... + def from_dicts(cls, headings: list[str], table_data: Sequence[dict[str, str]], line: int | None = None) -> Self: ... @classmethod def from_data( - cls, headings: list[str], table_data: Sequence[Mapping[str, str] | _RowData] | None = None, line: int = 0 + cls, headings: list[str], table_data: Sequence[dict[str, str] | _RowData] | None = None, line: int = 0 ) -> Table: ... class Row: From b7eb5c63de651f70140dd80096764af5ca6ce07c Mon Sep 17 00:00:00 2001 From: dhairya05 Date: Tue, 10 Nov 2026 14:16:40 +0530 Subject: [PATCH 4/4] [behave] Use Never instead of the deprecated NoReturn Table.assert_equals asserts and then raises NotImplementedError, so it never returns; Never is the non-deprecated spelling for that. --- stubs/behave/behave/model.pyi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/stubs/behave/behave/model.pyi b/stubs/behave/behave/model.pyi index 2156b43edff2..85065b6ca917 100644 --- a/stubs/behave/behave/model.pyi +++ b/stubs/behave/behave/model.pyi @@ -1,8 +1,8 @@ from _typeshed import Incomplete from collections import OrderedDict from collections.abc import Iterable, Iterator, Mapping, Sequence -from typing import ClassVar, NoReturn, TypeAlias, TypeVar, overload -from typing_extensions import Self +from typing import ClassVar, TypeAlias, TypeVar, overload +from typing_extensions import Never, Self from behave.model_core import Replayable @@ -38,7 +38,7 @@ class Table(Replayable): def __getitem__(self, index: slice) -> list[Row]: ... # Always raises: the comparison is asserted and then `NotImplementedError` is raised. - def assert_equals(self, data: object) -> NoReturn: ... + def assert_equals(self, data: object) -> Never: ... @classmethod def from_dicts(cls, headings: list[str], table_data: Sequence[dict[str, str]], line: int | None = None) -> Self: ... @classmethod