[SPARK-48646][PYTHON] Refine Python data source API docstring and type hints

[allisonwang-db]

What changes were proposed in this pull request?

This PR improves the docstring and type hints for classes and methods in datasource.py.

Why are the changes needed?

To improve type hint and docstring.

Does this PR introduce any user-facing change?

No

How was this patch tested?

Existing docs test.

Was this patch authored or co-authored using generative AI tooling?

No

[allisonwang-db]

cc @HyukjinKwon

[HyukjinKwon]

Let's fix MyPy failures though:

annotations failed mypy checks:
python/pyspark/sql/worker/python_streaming_sink_runner.py:118: error: Unused "type: ignore" comment  [unused-ignore]
python/pyspark/sql/worker/python_streaming_sink_runner.py:120: error: Unused "type: ignore" comment  [unused-ignore]
python/pyspark/sql/worker/commit_data_source_write.py:93: error: Unused "type: ignore" comment  [unused-ignore]
python/pyspark/sql/worker/commit_data_source_write.py:95: error: Unused "type: ignore" comment  [unused-ignore]

[xinrong-meng]

LGTM after tests passed, thank you!

[HyukjinKwon]

Merged to master.