docs: code samples for DataFrame.rename, Series.rename (#293)

BEGIN_COMMIT_OVERRIDE
docs: code samples for `rename` , `size` (#293)

docs: code samples for `Series.{name, std, agg}` (#293)
END_COMMIT_OVERRIDE

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:
- [ ] Make sure to open an issue as a [bug/issue](https://togithub.com/googleapis/python-bigquery-dataframes/issues/new/choose) before writing your code!  That way we can discuss the change, evaluate designs, and agree on the general idea
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [x] Appropriate docs were updated (if necessary)
  - `DataFrame.size`: https://screenshot.googleplex.com/55MHXNuAamdfbud
  - `Series.size`: https://screenshot.googleplex.com/5ve4T8UJq2TUiWb
  - `DataFrame.rename`: https://screenshot.googleplex.com/7eWsfcz8tmLx4pY
  - `Series.rename`: https://screenshot.googleplex.com/3HbXTxCaJVsbEzs
  - `Series.name`: https://screenshot.googleplex.com/7FpNDWJEyiqGLpN
  - `Series.std`: https://screenshot.googleplex.com/4RSTC8s2tYYK5cW
  - `Series.agg`: https://screenshot.googleplex.com/63TmACx23TPJu2K

Fixes internal issues 317997641 and 317998300 🦕

Author: shobsi

third_party/bigframes_vendored/pandas/core/frame.py

@@ -1146,6 +1146,30 @@ def rename(
         Dict values must be unique (1-to-1). Labels not contained in a dict
         will be left as-is. Extra labels listed don't throw an error.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.display.progress_bar = None
+
+            >>> df = bpd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
+            >>> df
+               A  B
+            0  1  4
+            1  2  5
+            2  3  6
+            <BLANKLINE>
+            [3 rows x 2 columns]
+
+        Rename columns using a mapping:
+
+            >>> df.rename(columns={"A": "col1", "B": "col2"})
+               col1  col2
+            0     1     4
+            1     2     5
+            2     3     6
+            <BLANKLINE>
+            [3 rows x 2 columns]
+
         Args:
             columns (Mapping):
                 Dict-like from old column labels to new column labels.

third_party/bigframes_vendored/pandas/core/generic.py

@@ -29,6 +29,19 @@ def ndim(self) -> int:
     def size(self) -> int:
         """Return an int representing the number of elements in this object.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.display.progress_bar = None
+
+            >>> s = bpd.Series({'a': 1, 'b': 2, 'c': 3})
+            >>> s.size
+            3
+
+            >>> df = bpd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
+            >>> df.size
+            4
+
         Returns:
             int: Return the number of rows if Series. Otherwise return the number of
                 rows times number of columns if DataFrame.

third_party/bigframes_vendored/pandas/core/series.py

@@ -135,6 +135,35 @@ def name(self) -> Hashable:
         to form a DataFrame. It is also used whenever displaying the Series
         using the interpreter.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.display.progress_bar = None
+
+        For a Series:
+
+            >>> s = bpd.Series([1, 2, 3], dtype="Int64", name='Numbers')
+            >>> s
+            0    1
+            1    2
+            2    3
+            Name: Numbers, dtype: Int64
+            >>> s.name
+            'Numbers'
+
+        If the Series is part of a DataFrame:
+
+            >>> df = bpd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
+            >>> df
+               col1  col2
+            0     1     3
+            1     2     4
+            <BLANKLINE>
+            [2 rows x 2 columns]
+            >>> s = df["col1"]
+            >>> s.name
+            'col1'
+
         Returns:
             hashable object: The name of the Series, also the column name
                 if part of a DataFrame.
@@ -560,6 +589,27 @@ def agg(self, func):
         """
         Aggregate using one or more operations over the specified axis.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.display.progress_bar = None
+
+            >>> s = bpd.Series([1, 2, 3, 4])
+            >>> s
+            0    1
+            1    2
+            2    3
+            3    4
+            dtype: Int64
+
+            >>> s.agg('min')
+            1
+
+            >>> s.agg(['min', 'max'])
+            min    1.0
+            max    4.0
+            dtype: Float64
+
         Args:
             func (function):
                 Function to use for aggregating the data.
@@ -2292,6 +2342,29 @@ def std(
 
         Normalized by N-1 by default.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.display.progress_bar = None
+
+            >>> df = bpd.DataFrame({'person_id': [0, 1, 2, 3],
+            ...                     'age': [21, 25, 62, 43],
+            ...                     'height': [1.61, 1.87, 1.49, 2.01]}
+            ...                   ).set_index('person_id')
+            >>> df
+                       age  height
+            person_id
+            0           21    1.61
+            1           25    1.87
+            2           62    1.49
+            3           43    2.01
+            <BLANKLINE>
+            [4 rows x 2 columns]
+
+            >>> df.std()
+            age       18.786076
+            height     0.237417
+            dtype: Float64
 
         Returns
         -------
@@ -2649,6 +2722,34 @@ def rename(self, index, **kwargs) -> Series | None:
 
         Alternatively, change ``Series.name`` with a scalar value.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.display.progress_bar = None
+
+            >>> s = bpd.Series([1, 2, 3])
+            >>> s
+            0    1
+            1    2
+            2    3
+            dtype: Int64
+
+        You can changes the Series name by specifying a string scalar:
+
+            >>> s.rename("my_name")
+            0    1
+            1    2
+            2    3
+            Name: my_name, dtype: Int64
+
+        You can change the labels by specifying a mapping:
+
+            >>> s.rename({1: 3, 2: 5})
+            0    1
+            3    2
+            5    3
+            dtype: Int64
+
         Args:
             index (scalar, hashable sequence, dict-like or function optional):
                 Functions or dict-like are transformations to apply to
@@ -2990,3 +3091,29 @@ def values(self):
 
         """
         raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
+
+    @property
+    def size(self) -> int:
+        """Return the number of elements in the underlying data.
+
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.display.progress_bar = None
+
+        For Series:
+
+            >>> s = bpd.Series({'a': 1, 'b': 2, 'c': 3})
+            >>> s.size
+            3
+
+        For Index:
+
+            >>> idx = bpd.Index(bpd.Series([1, 2, 3]))
+            >>> idx.size
+            3
+
+        Returns:
+            int: Return the number of elements in the underlying data.
+        """
+        raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)