Fixed pandas-dev#46252. Added comments and updated strftime doc for maintenance. Added a TestPeriodIndexFormat class

Author: Sylvain MARIE

pandas/_libs/tslibs/period.pyx

@@ -1236,14 +1236,16 @@ cdef list extra_fmts = [(b"%q", b"^`AB`^"),
 cdef list str_extra_fmts = ["^`AB`^", "^`CD`^", "^`EF`^",
                             "^`GH`^", "^`IJ`^", "^`KL`^"]
 
+cdef inline int idx_first_nonfiscal_fmt = 3
+
 cdef str _period_strftime(int64_t value, int freq, bytes fmt):
     cdef:
         Py_ssize_t i
         npy_datetimestruct dts
         char *formatted
         bytes pat, brepl
         list found_pat = [False] * len(extra_fmts)
-        int quarter
+        int quarter, us, ps
         str result, repl
 
     get_date_info(value, freq, &dts)
@@ -1263,23 +1265,33 @@ cdef str _period_strftime(int64_t value, int freq, bytes fmt):
     result = util.char_to_string(formatted)
     free(formatted)
 
+    # Now we will fill the placeholders corresponding to our additional directives
+    # First prepare the contents
+    if any(found_pat[idx_first_nonfiscal_fmt:]):
+        # Save these to local vars as dts can be modified by get_yq below
+        us = dts.us
+        ps = dts.ps
+    if any(found_pat[0:idx_first_nonfiscal_fmt]):
+        # Note: this modifies `dts` in-place so that year becomes fiscal year
+        # However it looses the us and ps
+        quarter = get_yq(value, freq, &dts)
+
+    # Now do the filling per se
     for i in range(len(extra_fmts)):
         if found_pat[i]:
 
-            quarter = get_yq(value, freq, &dts)
-
-            if i == 0:
-                repl = str(quarter)
-            elif i == 1:  # %f, 2-digit year
+            if i == 0:  # %q, 1-digit quarter.
+                repl = f"{quarter}"
+            elif i == 1:  # %f, 2-digit 'Fiscal' year
                 repl = f"{(dts.year % 100):02d}"
-            elif i == 2:
+            elif i == 2:  # %F, 'Fiscal' year with a century
                 repl = str(dts.year)
-            elif i == 3:
-                repl = f"{(value % 1_000):03d}"
-            elif i == 4:
-                repl = f"{(value % 1_000_000):06d}"
-            elif i == 5:
-                repl = f"{(value % 1_000_000_000):09d}"
+            elif i == 3:  # %l, milliseconds
+                repl = f"{(us // 1_000):03d}"
+            elif i == 4:  # %u, microseconds
+                repl = f"{(us):06d}"
+            elif i == 5:  # %n, nanoseconds
+                repl = f"{((us * 1000) + (ps // 1000)):09d}"
 
             result = result.replace(str_extra_fmts[i], repl)
 
@@ -2332,7 +2344,8 @@ cdef class _Period(PeriodMixin):
         containing one or several directives.  The method recognizes the same
         directives as the :func:`time.strftime` function of the standard Python
         distribution, as well as the specific additional directives ``%f``,
-        ``%F``, ``%q``. (formatting & docs originally from scikits.timeries).
+        ``%F``, ``%q``, ``%l``, ``%u``, ``%n``.
+        (formatting & docs originally from scikits.timeries).
 
         +-----------+--------------------------------+-------+
         | Directive | Meaning                        | Notes |
@@ -2379,11 +2392,20 @@ cdef class _Period(PeriodMixin):
         |           | AM or PM.                      |       |
         +-----------+--------------------------------+-------+
         | ``%q``    | Quarter as a decimal number    |       |
-        |           | [01,04]                        |       |
+        |           | [1,4]                          |       |
         +-----------+--------------------------------+-------+
         | ``%S``    | Second as a decimal number     | \(4)  |
         |           | [00,61].                       |       |
         +-----------+--------------------------------+-------+
+        | ``%l``    | Millisecond as a decimal number|       |
+        |           | [000,999].                     |       |
+        +-----------+--------------------------------+-------+
+        | ``%u``    | Microsecond as a decimal number|       |
+        |           | [000000,999999].               |       |
+        +-----------+--------------------------------+-------+
+        | ``%n``    | Nanosecond as a decimal number |       |
+        |           | [000000000,999999999].         |       |
+        +-----------+--------------------------------+-------+
         | ``%U``    | Week number of the year        | \(5)  |
         |           | (Sunday as the first day of    |       |
         |           | the week) as a decimal number  |       |

pandas/tests/io/formats/test_format.py

@@ -1,8 +1,10 @@
 """
 Test output formatting for Series/DataFrame, including to_string & reprs
 """
-
-from datetime import datetime
+from datetime import (
+    datetime,
+    time,
+)
 from io import StringIO
 import itertools
 from operator import methodcaller
@@ -47,6 +49,13 @@
 use_32bit_repr = is_platform_windows() or not IS64
 
 
+def get_local_am_pm():
+    """Return the AM and PM strings returned by strftime in current locale"""
+    am_local = time(1).strftime("%p")
+    pm_local = time(13).strftime("%p")
+    return am_local, pm_local
+
+
 @pytest.fixture(params=["string", "pathlike", "buffer"])
 def filepath_or_buffer_id(request):
     """
@@ -3167,6 +3176,66 @@ def test_str(self):
         assert str(NaT) == "NaT"
 
 
+class TestPeriodIndexFormat:
+    def test_period(self):
+        """Basic test for period formatting with default format."""
+        p = pd.PeriodIndex([datetime(2003, 1, 1, 12), None], freq="H")
+        # format is equivalent to strftime(None)
+        formatted = p.format()
+        assert formatted[0] == p[0].strftime(None)
+        assert formatted[0] == "2003-01-01 12:00"  # default: minutes not shown
+        assert formatted[1] == "NaT"
+
+        p = pd.period_range("2003-01-01 12:01:01.123456789", periods=2, freq="n")
+        # format is equivalent to strftime(None)
+        formatted = p.format()
+        assert formatted[0] == p[0].strftime(None)
+        assert formatted[0] == "2003-01-01 12:01:01.123456789"
+        assert formatted[1] == "2003-01-01 12:01:01.123456790"
+
+    def test_period_custom(self):
+        # GH46252
+
+        # Get locale-specific reference
+        am_local, pm_local = get_local_am_pm()
+
+        # 3 digits
+        p = pd.period_range("2003-01-01 12:01:01.123", periods=2, freq="l")
+        formatted = p.format(date_format="%y %I:%M:%S%p (ms=%l us=%u ns=%n)")
+        assert formatted[0] == f"03 12:01:01{pm_local} (ms=123 us=123000 ns=123000000)"
+        assert formatted[1] == f"03 12:01:01{pm_local} (ms=124 us=124000 ns=124000000)"
+
+        # 6 digits
+        p = pd.period_range("2003-01-01 12:01:01.123456", periods=2, freq="u")
+        formatted = p.format(date_format="%y %I:%M:%S%p (ms=%l us=%u ns=%n)")
+        assert formatted[0] == f"03 12:01:01{pm_local} (ms=123 us=123456 ns=123456000)"
+        assert formatted[1] == f"03 12:01:01{pm_local} (ms=123 us=123457 ns=123457000)"
+
+        # 9 digits
+        p = pd.period_range("2003-01-01 12:01:01.123456789", periods=2, freq="n")
+        formatted = p.format(date_format="%y %I:%M:%S%p (ms=%l us=%u ns=%n)")
+        assert formatted[0] == f"03 12:01:01{pm_local} (ms=123 us=123456 ns=123456789)"
+        assert formatted[1] == f"03 12:01:01{pm_local} (ms=123 us=123456 ns=123456790)"
+
+    def test_period_tz(self):
+        """Test formatting periods created from a datetime with timezone."""
+
+        # This timestamp is in 2013 in Europe/Paris but is 2012 in UTC
+        dt = pd.to_datetime(["2013-01-01 00:00:00+01:00"], utc=True)
+
+        # Converting to a period looses the timezone information
+        # Since tz is currently set as utc, we'll see 2012
+        with tm.assert_produces_warning(UserWarning, match="will drop timezone"):
+            p = dt.to_period(freq="H")
+        assert p.format()[0] == "2012-12-31 23:00"
+
+        # If tz is currently set as paris before conversion, we'll see 2013
+        dt = dt.tz_convert("Europe/Paris")
+        with tm.assert_produces_warning(UserWarning, match="will drop timezone"):
+            p = dt.to_period(freq="H")
+        assert p.format()[0] == "2013-01-01 00:00"
+
+
 class TestDatetimeIndexFormat:
     def test_datetime(self):
         formatted = pd.to_datetime([datetime(2003, 1, 1, 12), NaT]).format()