format_param¶

format_param(param: Parameter, hints: dict[str, Any], ctx: StubContext, raw_ann_override: str | None = None, docstring_type: str | None = None) → str[source]¶

Format a single inspect.Parameter as a stub-ready string.

Resolution order for the annotation string:

raw_ann_override — when provided and it references a registered alias module prefix (e.g. "types."), the raw AST string is used directly. This preserves alias names that Python’s typing.Union flattens at runtime.
hints dict — resolved type hints from get_hints_for_method().
param.annotation — the raw inspect.Parameter annotation.
docstring_type — when provided and no annotation was found from sources 1–3, emitted as an inline # type: X comment rather than as a live annotation (making the inferred origin visible).

Parameters:

param (inspect.Parameter) – The parameter to format.
hints (dict) – Resolved type hints keyed by parameter name.
ctx (StubContext) – Passed through to annotation_to_str().
raw_ann_override (str or None, optional) – Raw annotation string from the AST pre-pass.
docstring_type (str or None, optional) – Type string inferred from the docstring. Only used when no other annotation source is available; emitted as # type: X comment.

Returns:

str – A formatted string such as "x: int", "size: float = 1.0", "*args: str", or "**kwargs".

Examples

>>> import inspect
>>> from stubpy.context import StubContext
>>> from stubpy.annotations import format_param
>>> ctx = StubContext()
>>> p = inspect.Parameter("x", inspect.Parameter.POSITIONAL_OR_KEYWORD,
...                        annotation=int, default=0)
>>> format_param(p, {}, ctx)
'x: int = 0'
>>> p_star = inspect.Parameter("items", inspect.Parameter.VAR_POSITIONAL,
...                             annotation=str)
>>> format_param(p_star, {"items": str}, ctx)
'*items: str'