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 #45644has been automatically assigned in GitHub to PR creator.

[github-actions]

⚠️ GitHub issue #45644has 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]

@AlenkaFin 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.

[conbench-apache-arrow]

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

There were 3 benchmark results indicating a performance regression:

• Commit Run on amd64-m5-4xlarge-linux at 2026-05-14 13:54:55Z
  • file-read (Python) with compression=uncompressed, dataset=nyctaxi_2010-01, file_type=feather, output_type=table
  • file-read (Python) with compression=uncompressed, dataset=fanniemae_2016Q4, file_type=feather, output_type=dataframe
• and 1 more (see the report linked below)

The full Conbench report has more details. It also includes information about 14 possible false positives for unstable benchmarks that are known to sometimes produce them.

[conbench-apache-arrow]

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

There were 3 benchmark results indicating a performance regression:

• Commit Run on amd64-m5-4xlarge-linux at 2026-05-14 13:54:55Z
  • file-read (Python) with compression=uncompressed, dataset=nyctaxi_2010-01, file_type=feather, output_type=table
  • file-read (Python) with compression=uncompressed, dataset=fanniemae_2016Q4, file_type=feather, output_type=dataframe
• and 1 more (see the report linked below)

The full Conbench report has more details. It also includes information about 14 possible false positives for unstable benchmarks that are known to sometimes produce them.