Merge branch 'main' into pandas.tseries.offsets.BMonthEnd

Author: tuhinsharma121

ci/code_checks.sh

@@ -138,7 +138,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.RangeIndex.start SA01" \
         -i "pandas.RangeIndex.step SA01" \
         -i "pandas.RangeIndex.stop SA01" \
-        -i "pandas.Series.case_when RT03" \
         -i "pandas.Series.cat.add_categories PR01,PR02" \
         -i "pandas.Series.cat.as_ordered PR01" \
         -i "pandas.Series.cat.as_unordered PR01" \
@@ -229,7 +228,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Series.str.strip RT03" \
         -i "pandas.Series.str.swapcase RT03" \
         -i "pandas.Series.str.title RT03" \
-        -i "pandas.Series.str.translate RT03,SA01" \
         -i "pandas.Series.str.upper RT03" \
         -i "pandas.Series.str.wrap RT03,SA01" \
         -i "pandas.Series.str.zfill RT03" \
@@ -324,7 +322,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.api.extensions.ExtensionArray._reduce RT03,SA01" \
         -i "pandas.api.extensions.ExtensionArray._values_for_factorize SA01" \
         -i "pandas.api.extensions.ExtensionArray.astype SA01" \
-        -i "pandas.api.extensions.ExtensionArray.copy RT03,SA01" \
         -i "pandas.api.extensions.ExtensionArray.dropna RT03,SA01" \
         -i "pandas.api.extensions.ExtensionArray.dtype SA01" \
         -i "pandas.api.extensions.ExtensionArray.duplicated RT03,SA01" \
@@ -337,7 +334,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.api.extensions.ExtensionArray.nbytes SA01" \
         -i "pandas.api.extensions.ExtensionArray.ndim SA01" \
         -i "pandas.api.extensions.ExtensionArray.ravel RT03,SA01" \
-        -i "pandas.api.extensions.ExtensionArray.shape SA01" \
         -i "pandas.api.extensions.ExtensionArray.shift SA01" \
         -i "pandas.api.extensions.ExtensionArray.take RT03" \
         -i "pandas.api.extensions.ExtensionArray.tolist RT03,SA01" \
@@ -568,7 +564,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.tseries.offsets.BQuarterEnd.normalize GL08" \
         -i "pandas.tseries.offsets.BQuarterEnd.rule_code GL08" \
         -i "pandas.tseries.offsets.BQuarterEnd.startingMonth GL08" \
-        -i "pandas.tseries.offsets.BYearBegin PR02" \
         -i "pandas.tseries.offsets.BYearBegin.freqstr SA01" \
         -i "pandas.tseries.offsets.BYearBegin.is_on_offset GL08" \
         -i "pandas.tseries.offsets.BYearBegin.month GL08" \
@@ -831,7 +826,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.tseries.offsets.WeekOfMonth.rule_code GL08" \
         -i "pandas.tseries.offsets.WeekOfMonth.week GL08" \
         -i "pandas.tseries.offsets.WeekOfMonth.weekday GL08" \
-        -i "pandas.tseries.offsets.YearBegin PR02" \
         -i "pandas.tseries.offsets.YearBegin.freqstr SA01" \
         -i "pandas.tseries.offsets.YearBegin.is_on_offset GL08" \
         -i "pandas.tseries.offsets.YearBegin.month GL08" \

doc/source/getting_started/intro_tutorials/01_table_oriented.rst

@@ -192,8 +192,8 @@ Check more options on ``describe`` in the user guide section about :ref:`aggrega
 .. note::
     This is just a starting point. Similar to spreadsheet
     software, pandas represents data as a table with columns and rows. Apart
-    from the representation, also the data manipulations and calculations
-    you would do in spreadsheet software are supported by pandas. Continue
+    from the representation, the data manipulations and calculations
+    you would do in spreadsheet software are also supported by pandas. Continue
     reading the next tutorials to get started!
 
 .. raw:: html
@@ -204,7 +204,7 @@ Check more options on ``describe`` in the user guide section about :ref:`aggrega
 -  Import the package, aka ``import pandas as pd``
 -  A table of data is stored as a pandas ``DataFrame``
 -  Each column in a ``DataFrame`` is a ``Series``
--  You can do things by applying a method to a ``DataFrame`` or ``Series``
+-  You can do things by applying a method on a ``DataFrame`` or ``Series``
 
 .. raw:: html
 
@@ -215,7 +215,7 @@ Check more options on ``describe`` in the user guide section about :ref:`aggrega
     <div class="d-flex flex-row gs-torefguide">
         <span class="badge badge-info">To user guide</span>
 
-A more extended explanation to ``DataFrame`` and ``Series`` is provided in the :ref:`introduction to data structures <dsintro>`.
+A more extended explanation of ``DataFrame`` and ``Series`` is provided in the :ref:`introduction to data structures <dsintro>` page.
 
 .. raw:: html
 

doc/source/getting_started/intro_tutorials/02_read_write.rst

@@ -172,11 +172,11 @@ The method :meth:`~DataFrame.info` provides technical information about a
 -  The table has 12 columns. Most columns have a value for each of the
    rows (all 891 values are ``non-null``). Some columns do have missing
    values and less than 891 ``non-null`` values.
--  The columns ``Name``, ``Sex``, ``Cabin`` and ``Embarked`` consists of
+-  The columns ``Name``, ``Sex``, ``Cabin`` and ``Embarked`` consist of
    textual data (strings, aka ``object``). The other columns are
-   numerical data with some of them whole numbers (aka ``integer``) and
-   others are real numbers (aka ``float``).
--  The kind of data (characters, integers,…) in the different columns
+   numerical data, some of them are whole numbers (``integer``) and
+   others are real numbers (``float``).
+-  The kind of data (characters, integers, …) in the different columns
    are summarized by listing the ``dtypes``.
 -  The approximate amount of RAM used to hold the DataFrame is provided
    as well.
@@ -194,7 +194,7 @@ The method :meth:`~DataFrame.info` provides technical information about a
 -  Getting data in to pandas from many different file formats or data
    sources is supported by ``read_*`` functions.
 -  Exporting data out of pandas is provided by different
-   ``to_*``\ methods.
+   ``to_*`` methods.
 -  The ``head``/``tail``/``info`` methods and the ``dtypes`` attribute
    are convenient for a first check.
 

doc/source/getting_started/intro_tutorials/03_subset_data.rst

@@ -300,7 +300,7 @@ want to select.
         </li>
     </ul>
 
-When using the column names, row labels or a condition expression, use
+When using column names, row labels or a condition expression, use
 the ``loc`` operator in front of the selection brackets ``[]``. For both
 the part before and after the comma, you can use a single label, a list
 of labels, a slice of labels, a conditional expression or a colon. Using
@@ -342,7 +342,7 @@ the name ``anonymous`` to the first 3 elements of the fourth column:
     <div class="d-flex flex-row gs-torefguide">
         <span class="badge badge-info">To user guide</span>
 
-See the user guide section on :ref:`different choices for indexing <indexing.choice>` to get more insight in the usage of ``loc`` and ``iloc``.
+See the user guide section on :ref:`different choices for indexing <indexing.choice>` to get more insight into the usage of ``loc`` and ``iloc``.
 
 .. raw:: html
 
@@ -357,10 +357,8 @@ See the user guide section on :ref:`different choices for indexing <indexing.cho
 -  Inside these square brackets, you can use a single column/row label, a list
    of column/row labels, a slice of labels, a conditional expression or
    a colon.
--  Select specific rows and/or columns using ``loc`` when using the row
-   and column names.
--  Select specific rows and/or columns using ``iloc`` when using the
-   positions in the table.
+-  Use ``loc`` for label-based selection (using row/column names).
+-  Use ``iloc`` for position-based selection (using table positions).
 -  You can assign new values to a selection based on ``loc``/``iloc``.
 
 .. raw:: html

doc/source/getting_started/intro_tutorials/04_plotting.rst

@@ -85,7 +85,7 @@ I want to plot only the columns of the data table with the data from Paris.
     air_quality["station_paris"].plot()
     plt.show()
 
-To plot a specific column, use the selection method of the
+To plot a specific column, use a selection method from the
 :ref:`subset data tutorial <10min_tut_03_subset>` in combination with the :meth:`~DataFrame.plot`
 method. Hence, the :meth:`~DataFrame.plot` method works on both ``Series`` and
 ``DataFrame``.
@@ -127,7 +127,7 @@ standard Python to get an overview of the available plot methods:
     ]
 
 .. note::
-    In many development environments as well as IPython and
+    In many development environments such as IPython and
     Jupyter Notebook, use the TAB button to get an overview of the available
     methods, for example ``air_quality.plot.`` + TAB.
 
@@ -238,7 +238,7 @@ This strategy is applied in the previous example:
 
 -  The ``.plot.*`` methods are applicable on both Series and DataFrames.
 -  By default, each of the columns is plotted as a different element
-   (line, boxplot,…).
+   (line, boxplot, …).
 -  Any plot created by pandas is a Matplotlib object.
 
 .. raw:: html

doc/source/getting_started/intro_tutorials/05_add_columns.rst

@@ -89,8 +89,8 @@ values in each row*.
         </li>
     </ul>
 
-Also other mathematical operators (``+``, ``-``, ``*``, ``/``,…) or
-logical operators (``<``, ``>``, ``==``,…) work element-wise. The latter was already
+Other mathematical operators (``+``, ``-``, ``*``, ``/``, …) and logical
+operators (``<``, ``>``, ``==``, …) also work element-wise. The latter was already
 used in the :ref:`subset data tutorial <10min_tut_03_subset>` to filter
 rows of a table using a conditional expression.
 

doc/source/getting_started/intro_tutorials/06_calculate_statistics.rst

@@ -235,7 +235,7 @@ category in a column.
         </li>
     </ul>
 
-The function is a shortcut, as it is actually a groupby operation in combination with counting of the number of records
+The function is a shortcut, it is actually a groupby operation in combination with counting the number of records
 within each group:
 
 .. ipython:: python

doc/source/getting_started/intro_tutorials/08_combine_dataframes.rst

@@ -137,7 +137,7 @@ Hence, the resulting table has 3178 = 1110 + 2068 rows.
     Most operations like concatenation or summary statistics are by default
     across rows (axis 0), but can be applied across columns as well.
 
-Sorting the table on the datetime information illustrates also the
+Sorting the table on the datetime information also illustrates the
 combination of both tables, with the ``parameter`` column defining the
 origin of the table (either ``no2`` from table ``air_quality_no2`` or
 ``pm25`` from table ``air_quality_pm25``):
@@ -286,7 +286,7 @@ between the two tables.
     <div class="d-flex flex-row gs-torefguide">
         <span class="badge badge-info">To user guide</span>
 
-pandas supports also inner, outer, and right joins.
+pandas also supports inner, outer, and right joins.
 More information on join/merge of tables is provided in the user guide section on
 :ref:`database style merging of tables <merging.join>`. Or have a look at the
 :ref:`comparison with SQL<compare_with_sql.join>` page.
@@ -300,7 +300,7 @@ More information on join/merge of tables is provided in the user guide section o
     <div class="shadow gs-callout gs-callout-remember">
         <h4>REMEMBER</h4>
 
--  Multiple tables can be concatenated both column-wise and row-wise using
+-  Multiple tables can be concatenated column-wise or row-wise using
    the ``concat`` function.
 -  For database-like merging/joining of tables, use the ``merge``
    function.

doc/source/getting_started/intro_tutorials/09_timeseries.rst

@@ -77,9 +77,9 @@ I want to work with the dates in the column ``datetime`` as datetime objects ins
 
 Initially, the values in ``datetime`` are character strings and do not
 provide any datetime operations (e.g. extract the year, day of the
-week,…). By applying the ``to_datetime`` function, pandas interprets the
+week, …). By applying the ``to_datetime`` function, pandas interprets the
 strings and convert these to datetime (i.e. ``datetime64[ns, UTC]``)
-objects. In pandas we call these datetime objects similar to
+objects. In pandas we call these datetime objects that are similar to
 ``datetime.datetime`` from the standard library as :class:`pandas.Timestamp`.
 
 .. raw:: html
@@ -117,7 +117,7 @@ length of our time series:
     air_quality["datetime"].max() - air_quality["datetime"].min()
 
 The result is a :class:`pandas.Timedelta` object, similar to ``datetime.timedelta``
-from the standard Python library and defining a time duration.
+from the standard Python library which defines a time duration.
 
 .. raw:: html
 
@@ -257,7 +257,7 @@ the adapted time scale on plots. Let’s apply this on our data.
     <ul class="task-bullet">
         <li>
 
-Create a plot of the :math:`NO_2` values in the different stations from the 20th of May till the end of 21st of May
+Create a plot of the :math:`NO_2` values in the different stations from May 20th till the end of May 21st.
 
 .. ipython:: python
     :okwarning:
@@ -310,7 +310,7 @@ converting secondly data into 5-minutely data).
 The :meth:`~Series.resample` method is similar to a groupby operation:
 
 -  it provides a time-based grouping, by using a string (e.g. ``M``,
-   ``5H``,…) that defines the target frequency
+   ``5H``, …) that defines the target frequency
 -  it requires an aggregation function such as ``mean``, ``max``,…
 
 .. raw:: html

doc/source/getting_started/intro_tutorials/10_text_data.rst

@@ -134,8 +134,8 @@ only one countess on the Titanic, we get one row as a result.
 .. note::
     More powerful extractions on strings are supported, as the
     :meth:`Series.str.contains` and :meth:`Series.str.extract` methods accept `regular
-    expressions <https://docs.python.org/3/library/re.html>`__, but out of
-    scope of this tutorial.
+    expressions <https://docs.python.org/3/library/re.html>`__, but are out of
+    the scope of this tutorial.
 
 .. raw:: html
 
@@ -200,7 +200,7 @@ In the "Sex" column, replace values of "male" by "M" and values of "female" by "
 
 Whereas :meth:`~Series.replace` is not a string method, it provides a convenient way
 to use mappings or vocabularies to translate certain values. It requires
-a ``dictionary`` to define the mapping ``{from : to}``.
+a ``dictionary`` to define the mapping ``{from: to}``.
 
 .. raw:: html
 

doc/source/user_guide/merging.rst

@@ -1073,7 +1073,7 @@ compare two :class:`DataFrame` or :class:`Series`, respectively, and summarize t
    df.compare(df2)
 
 By default, if two corresponding values are equal, they will be shown as ``NaN``.
-Furthermore, if all values in an entire row / column, the row / column will be
+Furthermore, if all values in an entire row / column are equal, that row / column will be
 omitted from the result. The remaining differences will be aligned on columns.
 
 Stack the differences on rows.

pandas/_libs/tslibs/offsets.pyx

@@ -2538,7 +2538,7 @@ cdef class BYearBegin(YearOffset):
     """
     DateOffset increments between the first business day of the year.
 
-    Parameters
+    Attributes
     ----------
     n : int, default 1
         The number of years represented.
@@ -2633,7 +2633,7 @@ cdef class YearBegin(YearOffset):
 
     YearBegin goes to the next date which is the start of the year.
 
-    Parameters
+    Attributes
     ----------
     n : int, default 1
         The number of years represented.

pandas/core/arrays/base.py

@@ -610,6 +610,13 @@ def shape(self) -> Shape:
         """
         Return a tuple of the array dimensions.
 
+        See Also
+        --------
+        numpy.ndarray.shape : Similar attribute which returns the shape of an array.
+        DataFrame.shape : Return a tuple representing the dimensionality of the
+            DataFrame.
+        Series.shape : Return a tuple representing the dimensionality of the Series.
+
         Examples
         --------
         >>> arr = pd.array([1, 2, 3])
@@ -1604,9 +1611,19 @@ def copy(self) -> Self:
         """
         Return a copy of the array.
 
+        This method creates a copy of the `ExtensionArray` where modifying the
+        data in the copy will not affect the original array. This is useful when
+        you want to manipulate data without altering the original dataset.
+
         Returns
         -------
         ExtensionArray
+            A new `ExtensionArray` object that is a copy of the current instance.
+
+        See Also
+        --------
+        DataFrame.copy : Return a copy of the DataFrame.
+        Series.copy : Return a copy of the Series.
 
         Examples
         --------

pandas/core/series.py

@@ -5324,6 +5324,7 @@ def case_when(
         Returns
         -------
         Series
+            A new Series with values replaced based on the provided conditions.
 
         See Also
         --------

pandas/core/strings/accessor.py

@@ -2408,7 +2408,11 @@ def translate(self, table):
         """
         Map all characters in the string through the given mapping table.
 
-        Equivalent to standard :meth:`str.translate`.
+        This method is equivalent to the standard :meth:`str.translate`
+        method for strings. It maps each character in the string to a new
+        character according to the translation table provided. Unmapped
+        characters are left unchanged, while characters mapped to None
+        are removed.
 
         Parameters
         ----------
@@ -2421,6 +2425,14 @@ def translate(self, table):
         Returns
         -------
         Series or Index
+            A new Series or Index with translated strings.
+
+        See Also
+        --------
+        Series.str.replace : Replace occurrences of pattern/regex in the
+            Series with some other string.
+        Index.str.replace : Replace occurrences of pattern/regex in the
+            Index with some other string.
 
         Examples
         --------

pandas/tests/indexes/test_common.py

@@ -270,9 +270,7 @@ def test_searchsorted_monotonic(self, index_flat, request):
             # all values are the same, expected_right should be length
             expected_right = len(index)
 
-        # test _searchsorted_monotonic in all cases
-        # test searchsorted only for increasing
-        if index.is_monotonic_increasing:
+        if index.is_monotonic_increasing or index.is_monotonic_decreasing:
             ssm_left = index._searchsorted_monotonic(value, side="left")
             assert expected_left == ssm_left
 
@@ -284,13 +282,6 @@ def test_searchsorted_monotonic(self, index_flat, request):
 
             ss_right = index.searchsorted(value, side="right")
             assert expected_right == ss_right
-
-        elif index.is_monotonic_decreasing:
-            ssm_left = index._searchsorted_monotonic(value, side="left")
-            assert expected_left == ssm_left
-
-            ssm_right = index._searchsorted_monotonic(value, side="right")
-            assert expected_right == ssm_right
         else:
             # non-monotonic should raise.
             msg = "index must be monotonic increasing or decreasing"