Implement ParamModel: A Parameterized subclass based on type annotations

[philippjfr]

Based on discussion in #1066 I prototyped ParamModel.

Summary

Adds ParamModel, a new Parameterized subclass that synthesises Parameter instances automatically from PEP 526 type annotations. This gives users a dataclass-like authoring experience without requiring manual Parameter instantiation for common cases.

Motivation

After investigating @dataclass_transform, it became clear that the decorator cannot bind RHS Parameter descriptor types to LHS attribute types in a way that satisfies type checkers, you'd still need to repeat yourself (string_param: str = String()) and even then checkers would see String[str], not str. Additionally, dataclass_transform requires every field specifier to be enumerated upfront, which is impossible at ParameterizedMetaclass definition time because not all Parameter subclasses exist yet.

'ParamField', sidesteps these constraints entirely: the metaclass handles synthesis at class creation time, and a dedicated ParamField() factory covers the cases where users need to supply explicit parameter configuration.

Changes

ParamModel (decorated with @dataclass_transform(field_specifiers=(ParamField,))) overrides __new__ to walk the class __annotations__ dict at class creation time. For each non-private, non-ClassVar annotation it calls _annotation_parameter_factory to map the annotation to an appropriate Parameter subclass and infer constructor kwargs, then calls _build_parameter_from_field to construct the final Parameter object. String annotations are eval'd against the module globals to support from __future__ import annotations.

_annotation_parameter_factory handles the following mappings:

• bool → Boolean
• int → Integer
• float → Number
• str → String
• list[T] → List(item_type=T)
• tuple[...] → Tuple(length=N) (fixed-length) or Tuple (variable)
• dict[...] → Dict
• set → ClassSelector(class_=set)
• Literal[...] → Selector(objects=[...])
• T | None / Optional[T] → wraps the inner type with allow_None=True
• Annotated[T, {...}] → passes the mapping as extra kwargs to the parameter constructor
• Any / object → bare Parameter

ParamField() is a typed factory (three overloads) that returns a _FieldSpec sentinel. It accepts default, default_factory, a parameter override (class, callable, or instance), and arbitrary kwargs forwarded to the parameter constructor. Type checker overloads ensure that default: FT and default_factory: Callable[[], FT] both propagate FT to the attribute type, matching dataclass semantics.

_build_parameter_from_field merges the inferred factory and kwargs with anything supplied via Field, giving explicit Field values precedence. If a Parameter instance is passed as the parameter argument it is shallow-copied and mutated rather than re-instantiated.

Usage

class MyModel(ParamModel):
    # annotation-only → synthesised automatically
    name: str
    count: int = 0
    ratio: float | None = None
    tags: list[str]
    mode: Literal["fast", "slow"] = "fast"

    # explicit parameter config via Field
    label: str = ParamField(default="untitled", doc="Human-readable label")

    # explicit parameter type override
    path: str = ParamField(parameter=param.String, regex=r"^/")

    # Regular class attribute
    attr: ClassVar[str] = "foo"

[philippjfr]

Some suggestions instead of Field:

• ParamSpec / ParameterSpec
• ParamConfig / ParameterConfig
• ParameterHint

[jbednar]

param.Hints?

[philippjfr]

Alternatively param.Param.

[philippjfr]

And if we're already riffing on more succinct naming for the Parameter factory, then I'd also suggest ParamModel or ParamClass as names for TypedParameterized. TypedParameterized I no longer love because Parameterized is to some extent also typed.

[philippjfr]

Okay, my favorite proposal now is ParamModel and ParamField.

[jbednar]

TypedParameterized I no longer love because Parameterized is to some extent also typed.

I guess it would literally be ParameterizedFromTypeDeclarations?

Okay, my favorite proposal now is ParamModel and ParamField.

I don't personally love Model since it is used to mean so many things that it's lost all meaning for me, but I don't object since Pydantic uses that term.

[codecov]

Codecov Report

❌ Patch coverage is 88.38710% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.61%. Comparing base (9d24c4f) to head (b3664f8).

Files with missing lines	Patch %	Lines
param/typed.py	88.31%	18 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1133      +/-   ##
==========================================
- Coverage   88.61%   88.61%   -0.01%     
==========================================
  Files           9       10       +1     
  Lines        6072     6227     +155     
==========================================
+ Hits         5381     5518     +137     
- Misses        691      709      +18     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.