Skip to content

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

Open
alex-anast wants to merge 1 commit intoapache:mainfrom
alex-anast:alex-anast/gh-45644-doc-python-numpy-tz
Open

GH-45644: [Doc][Python] Document timezone loss when converting timestamp arrays to NumPy#49843
alex-anast wants to merge 1 commit intoapache:mainfrom
alex-anast:alex-anast/gh-45644-doc-python-numpy-tz

Conversation

@alex-anast
Copy link
Copy Markdown

@alex-anast alex-anast commented Apr 22, 2026

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.

@github-actions github-actions Bot added the awaiting review Awaiting review label Apr 22, 2026
@github-actions
Copy link
Copy Markdown

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

@github-actions
Copy link
Copy Markdown

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Doc][Python] Timestamp with tz loses its time zone after to_numpy

1 participant