[READY] Improved performance of Period's default formatter (period_format) (pandas-dev#51459)

* Improved performance of default period formatting (`period_format`). Added corresponding ASVs

* Improved ASV for period frames and datetimes

* What's new

* Update asv_bench/benchmarks/strftime.py

* Fixed whats new backticks

* Completed whatsnew

* Added ASVs for to_csv for period

* Aligned the namings

* Completed Whats new

* Added a docstring explaining why the ASV bench with custom date format was improved: the date_format parameter is not taken into account today.

* Moved whatsnew to 2.0.0

* Moved whatsnew to 2.1

* Improved docstring as per code review

* Renamed asv params as per code review

* Fixed ASV comment as per code review

* ASV: renamed parameters as per code review

* Improved `period_format`: now the performance is the same when no format is provided and if an explicit `fmt` is provided matching the actual default format for this `freq`

* Code review: Improved strftime ASV: set_index is now in the setup

* Removed useless main

* Removed wrong code

* Improved ASVs for period formatting: now there is a "default explicit" everywhere

* Update pandas/_libs/tslibs/period.pyx

* Update pandas/_libs/tslibs/period.pyx

* Update pandas/_libs/tslibs/period.pyx

* Minor refactoring to avoid retesting for none several time

* Fixed issue: bool does not exist, using bint

* Added missing quarter variable as cdef

* Fixed asv bug

* Code review: fixed docstring

* Update doc/source/whatsnew/v2.1.0.rst

* fixup

---------

Co-authored-by: Sylvain MARIE <[email protected]>
Co-authored-by: Marco Edward Gorelli <[email protected]>
Co-authored-by: MarcoGorelli <>

Author: 3 people

asv_bench/benchmarks/io/csv.py

@@ -12,6 +12,7 @@
     DataFrame,
     concat,
     date_range,
+    period_range,
     read_csv,
     to_datetime,
 )
@@ -98,24 +99,76 @@ def time_frame_date_no_format_index(self):
         self.data.to_csv(self.fname)
 
 
+class ToCSVPeriod(BaseIO):
+    fname = "__test__.csv"
+
+    params = ([1000, 10000], ["D", "H"])
+    param_names = ["nobs", "freq"]
+
+    def setup(self, nobs, freq):
+        rng = period_range(start="2000-01-01", periods=nobs, freq=freq)
+        self.data = DataFrame(rng)
+        if freq == "D":
+            self.default_fmt = "%Y-%m-%d"
+        elif freq == "H":
+            self.default_fmt = "%Y-%m-%d %H:00"
+
+    def time_frame_period_formatting_default(self, nobs, freq):
+        self.data.to_csv(self.fname)
+
+    def time_frame_period_formatting_default_explicit(self, nobs, freq):
+        self.data.to_csv(self.fname, date_format=self.default_fmt)
+
+    def time_frame_period_formatting(self, nobs, freq):
+        # Nb: `date_format` is not actually taken into account here today, so the
+        # performance is currently identical to `time_frame_period_formatting_default`
+        # above. This timer is therefore expected to degrade when GH#51621 is fixed.
+        # (Remove this comment when GH#51621 is fixed.)
+        self.data.to_csv(self.fname, date_format="%Y-%m-%d___%H:%M:%S")
+
+
+class ToCSVPeriodIndex(BaseIO):
+    fname = "__test__.csv"
+
+    params = ([1000, 10000], ["D", "H"])
+    param_names = ["nobs", "freq"]
+
+    def setup(self, nobs, freq):
+        rng = period_range(start="2000-01-01", periods=nobs, freq=freq)
+        self.data = DataFrame({"a": 1}, index=rng)
+        if freq == "D":
+            self.default_fmt = "%Y-%m-%d"
+        elif freq == "H":
+            self.default_fmt = "%Y-%m-%d %H:00"
+
+    def time_frame_period_formatting_index(self, nobs, freq):
+        self.data.to_csv(self.fname, date_format="%Y-%m-%d___%H:%M:%S")
+
+    def time_frame_period_formatting_index_default(self, nobs, freq):
+        self.data.to_csv(self.fname)
+
+    def time_frame_period_formatting_index_default_explicit(self, nobs, freq):
+        self.data.to_csv(self.fname, date_format=self.default_fmt)
+
+
 class ToCSVDatetimeBig(BaseIO):
     fname = "__test__.csv"
     timeout = 1500
     params = [1000, 10000, 100000]
-    param_names = ["obs"]
+    param_names = ["nobs"]
 
-    def setup(self, obs):
+    def setup(self, nobs):
         d = "2018-11-29"
         dt = "2018-11-26 11:18:27.0"
         self.data = DataFrame(
             {
-                "dt": [np.datetime64(dt)] * obs,
-                "d": [np.datetime64(d)] * obs,
-                "r": [np.random.uniform()] * obs,
+                "dt": [np.datetime64(dt)] * nobs,
+                "d": [np.datetime64(d)] * nobs,
+                "r": [np.random.uniform()] * nobs,
             }
         )
 
-    def time_frame(self, obs):
+    def time_frame(self, nobs):
         self.data.to_csv(self.fname)
 
 

asv_bench/benchmarks/strftime.py

@@ -7,58 +7,109 @@
 class DatetimeStrftime:
     timeout = 1500
     params = [1000, 10000]
-    param_names = ["obs"]
+    param_names = ["nobs"]
 
-    def setup(self, obs):
+    def setup(self, nobs):
         d = "2018-11-29"
         dt = "2018-11-26 11:18:27.0"
         self.data = pd.DataFrame(
             {
-                "dt": [np.datetime64(dt)] * obs,
-                "d": [np.datetime64(d)] * obs,
-                "r": [np.random.uniform()] * obs,
+                "dt": [np.datetime64(dt)] * nobs,
+                "d": [np.datetime64(d)] * nobs,
+                "r": [np.random.uniform()] * nobs,
             }
         )
 
-    def time_frame_date_to_str(self, obs):
+    def time_frame_date_to_str(self, nobs):
         self.data["d"].astype(str)
 
-    def time_frame_date_formatting_default(self, obs):
+    def time_frame_date_formatting_default(self, nobs):
+        self.data["d"].dt.strftime(date_format=None)
+
+    def time_frame_date_formatting_default_explicit(self, nobs):
         self.data["d"].dt.strftime(date_format="%Y-%m-%d")
 
-    def time_frame_date_formatting_custom(self, obs):
+    def time_frame_date_formatting_custom(self, nobs):
         self.data["d"].dt.strftime(date_format="%Y---%m---%d")
 
-    def time_frame_datetime_to_str(self, obs):
+    def time_frame_datetime_to_str(self, nobs):
         self.data["dt"].astype(str)
 
-    def time_frame_datetime_formatting_default_date_only(self, obs):
+    def time_frame_datetime_formatting_default(self, nobs):
+        self.data["dt"].dt.strftime(date_format=None)
+
+    def time_frame_datetime_formatting_default_explicit_date_only(self, nobs):
         self.data["dt"].dt.strftime(date_format="%Y-%m-%d")
 
-    def time_frame_datetime_formatting_default(self, obs):
+    def time_frame_datetime_formatting_default_explicit(self, nobs):
         self.data["dt"].dt.strftime(date_format="%Y-%m-%d %H:%M:%S")
 
-    def time_frame_datetime_formatting_default_with_float(self, obs):
+    def time_frame_datetime_formatting_default_with_float(self, nobs):
         self.data["dt"].dt.strftime(date_format="%Y-%m-%d %H:%M:%S.%f")
 
-    def time_frame_datetime_formatting_custom(self, obs):
+    def time_frame_datetime_formatting_custom(self, nobs):
         self.data["dt"].dt.strftime(date_format="%Y-%m-%d --- %H:%M:%S")
 
 
+class PeriodStrftime:
+    timeout = 1500
+    params = ([1000, 10000], ["D", "H"])
+    param_names = ["nobs", "freq"]
+
+    def setup(self, nobs, freq):
+        self.data = pd.DataFrame(
+            {
+                "p": pd.period_range(start="2000-01-01", periods=nobs, freq=freq),
+                "r": [np.random.uniform()] * nobs,
+            }
+        )
+        self.data["i"] = self.data["p"]
+        self.data.set_index("i", inplace=True)
+        if freq == "D":
+            self.default_fmt = "%Y-%m-%d"
+        elif freq == "H":
+            self.default_fmt = "%Y-%m-%d %H:00"
+
+    def time_frame_period_to_str(self, nobs, freq):
+        self.data["p"].astype(str)
+
+    def time_frame_period_formatting_default(self, nobs, freq):
+        self.data["p"].dt.strftime(date_format=None)
+
+    def time_frame_period_formatting_default_explicit(self, nobs, freq):
+        self.data["p"].dt.strftime(date_format=self.default_fmt)
+
+    def time_frame_period_formatting_index_default(self, nobs, freq):
+        self.data.index.format()
+
+    def time_frame_period_formatting_index_default_explicit(self, nobs, freq):
+        self.data.index.format(self.default_fmt)
+
+    def time_frame_period_formatting_custom(self, nobs, freq):
+        self.data["p"].dt.strftime(date_format="%Y-%m-%d --- %H:%M:%S")
+
+    def time_frame_period_formatting_iso8601_strftime_Z(self, nobs, freq):
+        self.data["p"].dt.strftime(date_format="%Y-%m-%dT%H:%M:%SZ")
+
+    def time_frame_period_formatting_iso8601_strftime_offset(self, nobs, freq):
+        """Not optimized yet as %z is not supported by `convert_strftime_format`"""
+        self.data["p"].dt.strftime(date_format="%Y-%m-%dT%H:%M:%S%z")
+
+
 class BusinessHourStrftime:
     timeout = 1500
     params = [1000, 10000]
-    param_names = ["obs"]
+    param_names = ["nobs"]
 
-    def setup(self, obs):
+    def setup(self, nobs):
         self.data = pd.DataFrame(
             {
-                "off": [offsets.BusinessHour()] * obs,
+                "off": [offsets.BusinessHour()] * nobs,
             }
         )
 
-    def time_frame_offset_str(self, obs):
+    def time_frame_offset_str(self, nobs):
         self.data["off"].apply(str)
 
-    def time_frame_offset_repr(self, obs):
+    def time_frame_offset_repr(self, nobs):
         self.data["off"].apply(repr)

asv_bench/benchmarks/tslibs/period.py

@@ -60,6 +60,10 @@ class PeriodUnaryMethods:
 
     def setup(self, freq):
         self.per = Period("2012-06-01", freq=freq)
+        if freq == "M":
+            self.default_fmt = "%Y-%m"
+        elif freq == "min":
+            self.default_fmt = "%Y-%m-%d %H:%M"
 
     def time_to_timestamp(self, freq):
         self.per.to_timestamp()
@@ -70,6 +74,21 @@ def time_now(self, freq):
     def time_asfreq(self, freq):
         self.per.asfreq("A")
 
+    def time_str(self, freq):
+        str(self.per)
+
+    def time_repr(self, freq):
+        repr(self.per)
+
+    def time_strftime_default(self, freq):
+        self.per.strftime(None)
+
+    def time_strftime_default_explicit(self, freq):
+        self.per.strftime(self.default_fmt)
+
+    def time_strftime_custom(self, freq):
+        self.per.strftime("%b. %d, %Y was a %A")
+
 
 class PeriodConstructor:
     params = [["D"], [True, False]]

doc/source/whatsnew/v2.1.0.rst

@@ -283,6 +283,7 @@ Performance improvements
 - Performance improvement when parsing strings to ``boolean[pyarrow]`` dtype (:issue:`51730`)
 - Performance improvement when searching an :class:`Index` sliced from other indexes (:issue:`51738`)
 - Performance improvement in :func:`concat` (:issue:`52291`, :issue:`52290`)
+- :class:`Period`'s default formatter (`period_format`) is now significantly (~twice) faster. This improves performance of ``str(Period)``, ``repr(Period)``, and :meth:`Period.strftime(fmt=None)`, as well as ``PeriodArray.strftime(fmt=None)``, ``PeriodIndex.strftime(fmt=None)`` and ``PeriodIndex.format(fmt=None)``. Finally, ``to_csv`` operations involving :class:`PeriodArray` or :class:`PeriodIndex` with default ``date_format`` are also significantly accelerated. (:issue:`51459`)
 - Performance improvement accessing :attr:`arrays.IntegerArrays.dtype` & :attr:`arrays.FloatingArray.dtype` (:issue:`52998`)
 - Performance improvement in :class:`Series` reductions (:issue:`52341`)
 - Performance improvement in :func:`concat` when ``axis=1`` and objects have different indexes (:issue:`52541`)
@@ -291,7 +292,6 @@ Performance improvements
 - Performance improvement in :meth:`Series.corr` and :meth:`Series.cov` for extension dtypes (:issue:`52502`)
 - Performance improvement in :meth:`Series.to_numpy` when dtype is a numpy float dtype and ``na_value`` is ``np.nan`` (:issue:`52430`)
 - Performance improvement in :meth:`~arrays.ArrowExtensionArray.to_numpy` (:issue:`52525`)
--
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_210.bug_fixes: