fix: tighten scalar UDF return type hints

[BharatDeva]

Which issue does this PR close?

Closes#1507.

Rationale for this change

The scalar UDF helper currently uses the same type variable for the Python callable return value and the declared Arrow return field. Those are different concepts: the callable returns Arrow arrays, while return_field can be an Arrow data type or field used to declare the UDF output.

Keeping those hints separate makes the public wrapper easier to use from type checkers and avoids implying that callers should pass an array object as the return field.

What changes are included in this PR?

This PR tightens the scalar UDF annotations in python/datafusion/user_defined.py:

• the callable return type is bounded to pa.Array
• the scalar UDF constructor accepts return_field: pa.Field
• the decorator form accepts return_field: pa.DataType | pa.Field

Are there any user-facing changes?

No runtime behavior changes. This only updates Python type hints for the scalar UDF wrapper.

Validation run locally:

• uvx ruff@0.15.1 check python/datafusion/user_defined.py - passed
• uvx ruff@0.15.1 format --check python/datafusion/user_defined.py - passed
• git diff --check origin/main...HEAD - passed

[kosiew]

@BharatDeva

Thanks for working on this.

Looks good overall. I only have one small documentation suggestion.

[kosiew]

Nice work separating the callable return type from the declared return field. Could we also update the public docstring from return_field (_R) to return_field (pa.DataType | pa.Field)?

That would keep the generated docs from suggesting that the declared field is tied to the callable's Arrow array return type.

[BharatDeva]

Thanks, updated the public docstring to use pa.DataType | pa.Field for return_field.

[kosiew]

@BharatDeva
Thanks for your contribution