GH-45644: [Doc][Python] Document timezone loss when converting timestamp arrays to NumPy

[alex-anast]

Rationale for this change

NumPy's datetime64 type does not support timezones. When converting a timezone-aware Arrow timestamp array to NumPy via to_numpy(), the timezone information is silently dropped. This behaviour is expected but undocumented, which can surprise users (see #45644).

What changes are included in this PR?

Adds a "Timezone-aware Timestamps" subsection to docs/source/python/numpy.rst that:

• Explains the timezone loss when calling to_numpy() on tz-aware timestamp arrays
• Shows a code example demonstrating the behavior
• Documents two alternatives: to_pandas() for tz-aware Series, and to_pylist() for Python datetime objects with tzinfo

Are these changes tested?

Documentation-only change. All code examples were verified against pyarrow 24.0.0 and sphinx-lint passes clean.

Are there any user-facing changes?

No behaviour changes. This adds documentation for existing behaviour.

AI-generated code disclosure

This PR was developed with assistance from an AI coding tool (Claude, Anthropic). All changes have been reviewed, understood, and verified.

• GitHub Issue: [Doc][Python] Timestamp with tz loses its time zone after to_numpy #45644
  Closes [Doc][Python] Timestamp with tz loses its time zone after to_numpy #45644

[github-actions]

⚠️ GitHub issue #45644 has been automatically assigned in GitHub to PR creator.

[github-actions]

⚠️ GitHub issue #45644 has been automatically assigned in GitHub to PR creator.

[AlenkaF]

Thank you for the PR, the change looks good to me!
One ask I have is to include the caveat when using to_pandas() in the case of nested types described in #41162 (works for structs and maps, not for lists; unions and list views would need to be checked).

[alex-anast]

Thanks for the review, @AlenkaF ! I've added a .. note:: block under the to_pandas() alternative documenting the nested types caveat.

Unrelated, but the most recent commit also fixed the Sphinx doctest failures -- the >>> examples were being picked up by pytest --doctest-glob and failing due to numpy output line-wrapping differences, so I added # doctest: +SKIP to those examples. Please let me know if there's a better way.

[AlenkaF]

Unrelated, but the most recent commit also fixed the Sphinx doctest failures -- the >>> examples were being picked up by pytest --doctest-glob and failing due to numpy output line-wrapping differences, so I added # doctest: +SKIP to those examples. Please let me know if there's a better way.

I would use +SKIP as little as possible and I would make changes only on the lines that are failing. Also, I like to use ELLIPSIS (...) where possible so you can still check the whole first line before the line break. If that makes sense?

[alex-anast]

@AlenkaF in the most recent iteration, I kept only what's necessary :) The final +SKIP allows for readability here, otherwise I would have to replace tzinfo=zoneinfo.ZoneInfo(key='UTC') with tzinfo=..

[AlenkaF]

Looking good, thank you for the updates!

One last thing I would like to bring up before we merge is the example of converting to NumPy through Pandas (to_pandas(timestamp_as_object=True).to_numpy()). I am undecided if this would be needed here or not, but am leaning towards yes. What do you think @alex-anast?

[AlenkaF]

@github-actions crossbow submit preview-docs

[github-actions]

Revision: 7dcd9df

Submitted crossbow builds: ursacomputing/crossbow @ actions-40c521d3da

Task	Status
preview-docs

[alex-anast]

Thanks for the suggestion @AlenkaF !
The PR is specifically about to_numpy() losing timezone information, so it makes sense to me to include an example for users to still end up with a NumPy array while preserving timezone info. It neither bloats the doc nor is it confusing to add, so I actually now include it in the implementation -- that's my thinking.

[AlenkaF]

@github-actions crossbow submit preview-docs

[github-actions]

Revision: cf094e6

Submitted crossbow builds: ursacomputing/crossbow @ actions-29ed4f5cc3

Task	Status
preview-docs

[AlenkaF]

Just one minor suggestion, otherwise LGTM, thanks!
https://s3.amazonaws.com/arrow-data/pr_docs/49843/python/numpy.html#timezone-aware-timestamps

[conbench-apache-arrow]

After merging your PR, Conbench analyzed the 0 benchmarking runs that have been run so far on merge-commit 1fc0e19.

None of the specified runs were found on the Conbench server.

The full Conbench report has more details.