From 429a4a5d0f30eecdffec37de9a879c634991ac5c Mon Sep 17 00:00:00 2001
From: Lily Zhang <32233490+junyazhang@users.noreply.github.com>
Date: Thu, 21 Mar 2024 14:21:49 -0700
Subject: [PATCH] chore: update docstring for astype (#485)

* chore: update docstring for astype

* minor fix

* minor fixes to pass doc test
---
 .../bigframes_vendored/pandas/core/generic.py | 51 ++++++++++++++-----
 1 file changed, 39 insertions(+), 12 deletions(-)

diff --git a/third_party/bigframes_vendored/pandas/core/generic.py b/third_party/bigframes_vendored/pandas/core/generic.py
index d1cf55c95b..1477640c29 100644
--- a/third_party/bigframes_vendored/pandas/core/generic.py
+++ b/third_party/bigframes_vendored/pandas/core/generic.py
@@ -123,28 +123,55 @@ def astype(self, dtype):
 
         Create a series of type ``Int64``:
 
-            >>> ser = bpd.Series([1, 2], dtype='Int64')
+            >>> ser = bpd.Series([2023010000246789, 1624123244123101, 1054834234120101], dtype='Int64')
             >>> ser
-            0    1
-            1    2
+            0    2023010000246789
+            1    1624123244123101
+            2    1054834234120101
             dtype: Int64
 
         Convert to ``Float64`` type:
 
             >>> ser.astype('Float64')
-            0    1.0
-            1    2.0
+            0    2023010000246789.0
+            1    1624123244123101.0
+            2    1054834234120101.0
             dtype: Float64
 
+        Convert to ``pd.ArrowDtype(pa.timestamp("us", tz="UTC"))`` type:
+
+            >>> ser.astype("timestamp[us, tz=UTC][pyarrow]")
+            0    2034-02-08 11:13:20.246789+00:00
+            1    2021-06-19 17:20:44.123101+00:00
+            2    2003-06-05 17:30:34.120101+00:00
+            dtype: timestamp[us, tz=UTC][pyarrow]
+
+        Note that this is equivalent of using ``to_datetime`` with ``unit='us'``:
+
+            >>> bpd.to_datetime(ser, unit='us', utc=True)
+            0    2034-02-08 11:13:20.246789+00:00
+            1    2021-06-19 17:20:44.123101+00:00
+            2    2003-06-05 17:30:34.120101+00:00
+            dtype: timestamp[us, tz=UTC][pyarrow]
+
+        Convert ``pd.ArrowDtype(pa.timestamp("us", tz="UTC"))`` type to ``Int64`` type:
+
+            >>> timestamp_ser = ser.astype("timestamp[us, tz=UTC][pyarrow]")
+            >>> timestamp_ser.astype('Int64')
+            0    2023010000246789
+            1    1624123244123101
+            2    1054834234120101
+            dtype: Int64
+
         Args:
             dtype (str or pandas.ExtensionDtype):
-                A dtype supported by BigQuery DataFrame include 'boolean','Float64','Int64',
-                'string', 'string[pyarrow]','timestamp[us, tz=UTC][pyarrow]',
-                'timestamp[us][pyarrow]','date32[day][pyarrow]','time64[us][pyarrow]'
-                A pandas.ExtensionDtype include pandas.BooleanDtype(), pandas.Float64Dtype(),
-                pandas.Int64Dtype(), pandas.StringDtype(storage="pyarrow"),
-                pd.ArrowDtype(pa.date32()), pd.ArrowDtype(pa.time64("us")),
-                pd.ArrowDtype(pa.timestamp("us")), pd.ArrowDtype(pa.timestamp("us", tz="UTC")).
+                A dtype supported by BigQuery DataFrame include ``'boolean'``, ``'Float64'``, ``'Int64'``,
+                ``'int64[pyarrow]'``, ``'string'``, ``'string[pyarrow]'``, ``'timestamp[us, tz=UTC][pyarrow]'``,
+                ``'timestamp\[us\]\[pyarrow\]'``, ``'date32\[day\]\[pyarrow\]'``, ``'time64\[us\]\[pyarrow\]'``.
+                A pandas.ExtensionDtype include ``pandas.BooleanDtype()``, ``pandas.Float64Dtype()``,
+                ``pandas.Int64Dtype()``, ``pandas.StringDtype(storage="pyarrow")``,
+                ``pd.ArrowDtype(pa.date32())``, ``pd.ArrowDtype(pa.time64("us"))``,
+                ``pd.ArrowDtype(pa.timestamp("us"))``, ``pd.ArrowDtype(pa.timestamp("us", tz="UTC"))``.
 
         Returns:
             same type as caller