Expression constructors are not mypy-compatible without the pydantic plugin

pyiceberg/expressions/init.py の UnboundPredicate、LiteralPredicate、UnaryPredicate のコンストラクターと、それらの term フィールド宣言から始めます。既存の validator の動作を確認し、その後、Pydantic プラグインなしの mypy が列挙された predicate コンストラクターを受け入れること、また文字列の term が実行時に引き続き正しく強制変換されることを確認します。

Constructing expression predicates like EqualTo("col", value) produces mypy errors because the Pydantic model field declarations use UnboundTerm as the type for term, and without the pydantic mypy plugin active, mypy generates __init__ signatures from the field types rather than from the explicit __init__ overrides.

Example:

from pyiceberg import expressions as ice

expr = ice.EqualTo("my_column", 42)

mypy output (v1.19.1, pyiceberg 0.11.0, no pydantic mypy plugin):

error: Argument 1 to "EqualTo" has incompatible type "str"; expected "UnboundTerm"  [arg-type]

Root cause:

The base classes define explicit __init__ methods that accept str | UnboundTerm:

• UnboundPredicate.__init__: def __init__(self, term: str | UnboundTerm, **kwargs: Any) -> None
• LiteralPredicate.__init__: def __init__(self, term: str | UnboundTerm, literal: Any | None = None, **kwargs: Any) -> None
• UnaryPredicate.__init__: def __init__(self, term: str | UnboundTerm, **_: Any) -> None

But since these classes extend IcebergBaseModel (Pydantic BaseModel), mypy ignores the explicit __init__ and instead generates the constructor signature from the field declaration term: UnboundTerm, which does not include str.

This affects all predicate constructors: EqualTo, NotEqualTo, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, IsNull, NotNull, IsNaN, NotNaN, In, NotIn, StartsWith, NotStartsWith.

Workaround:

Downstream projects can either enable the pydantic mypy plugin or suppress type checking for the affected call sites.

Possible fix:

Widen the field type annotation on UnboundPredicate from term: UnboundTerm to term: str | UnboundTerm with a validator that coerces str to UnboundTerm. This way the type seen by mypy (from the field declaration) matches what the constructor actually accepts at runtime, regardless of whether the pydantic mypy plugin is enabled.