Period ====== .. currentmodule:: pandasCore .. class:: Period Represents a period of time. Example ------- .. code-block:: python import pandasCore as pd # Create Period obj = pd.Period(...) Attributes ---------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Attribute - Description - Example * - :attr:`~Period.day` - Return the day of month (1-31) - * - :attr:`~Period.day_of_week` - Return the day of week (0=Monday, 6=Sunday) - * - :attr:`~Period.day_of_year` - Return the day of year (1-366) - * - :attr:`~Period.dayofweek` - Return the day of week (0=Monday, 6=Sunday) - * - :attr:`~Period.dayofyear` - Return the day of year (1-366) - * - :attr:`~Period.days_in_month` - Return the number of days in the current month - * - :attr:`~Period.end_time` - Return the end time of this period as a Timestamp - :ref:`View ` * - :attr:`~Period.freq` - Return the frequency string - * - :attr:`~Period.freqstr` - Return the frequency string - :ref:`View ` * - :attr:`~Period.hour` - Return the hour (0-23) - * - :attr:`~Period.is_leap_year` - Return True if the year is a leap year - * - :attr:`~Period.minute` - Return the minute (0-59) - * - :attr:`~Period.month` - Return the month (1-12) - :ref:`View ` * - :attr:`~Period.ordinal` - Return the ordinal value of this period - :ref:`View ` * - :attr:`~Period.quarter` - Return the quarter (1-4) - :ref:`View ` * - :attr:`~Period.qyear` - Return the fiscal year - * - :attr:`~Period.second` - Return the second (0-59) - * - :attr:`~Period.start_time` - Return the start time of this period as a Timestamp - :ref:`View ` * - :attr:`~Period.week` - Return the week of year (1-53) - * - :attr:`~Period.weekofyear` - Return the week of year (1-53) - * - :attr:`~Period.year` - Return the year this period belongs to - :ref:`View ` Construction ------------ .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Period.__init__` ``(value: object = None, freq: object = None, ordinal: object = None, year: object = None, month: object = None, quarter: object = None, day: object = None, hour: object = None, minute: object = None, second: object = None)`` - Represents a period of time. - :ref:`View ` Arithmetic ---------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Period.__add__` ``(arg0: typing.SupportsInt)`` - - * - :meth:`~Period.__sub__` ``(*args, **kwargs) | (arg0: typing.SupportsInt) | (arg0: pandasCore.Period)`` - - Comparison ---------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Period.__eq__` ``(arg0: object)`` - - * - :meth:`~Period.__ge__` ``(arg0: pandasCore.Period)`` - - * - :meth:`~Period.__gt__` ``(arg0: pandasCore.Period)`` - - * - :meth:`~Period.__le__` ``(arg0: pandasCore.Period)`` - - * - :meth:`~Period.__lt__` ``(arg0: pandasCore.Period)`` - - * - :meth:`~Period.__ne__` ``(arg0: object)`` - - Time Series ----------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Period.asfreq` ``(freq: str, how: str = 'E')`` - Convert Period to another frequency. - :ref:`View ` * - :meth:`~Period.to_timestamp` ``(freq: object = None, how: str = 'start')`` - Return the Timestamp representation of this Period. - :ref:`View ` Datetime Methods ---------------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Period.strftime` ``(fmt: object)`` - Convert to a string representation using the specified format. - :ref:`View ` Other Methods ------------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Period.__hash__` ``()`` - - * - :meth:`~Period.__repr__` ``()`` - - * - :meth:`~Period.__str__` ``()`` - - * - :meth:`~Period.isnat` ``()`` - Return True if the Period is NaT (Not a Time) - Code Examples ------------- The following examples are extracted from the test suite. .. _example-period-end_time-0: .. dropdown:: end_time (test_period.py:240) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 230 :emphasize-lines: 11 else: f_print_error(f"Start timestamp year/month wrong") return False # Convert to timestamp (end) ts_end = p.to_timestamp(how='end') f_print_success(f"to_timestamp(how='end'): {ts_end}") # Check start_time and end_time properties f_print_info(f"start_time: {p.start_time}") f_print_info(f"end_time: {p.end_time}") return True except Exception as e: f_print_error(f"Exception: {e}") return False def test_period_arithmetic(): """Test Period arithmetic operations""" .. _example-period-freqstr-1: .. dropdown:: freqstr (test_period.py:89) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 79 :emphasize-lines: 11 return False # Check quarter if p.quarter == 2: f_print_success(f"quarter is correct: {p.quarter}") else: f_print_error(f"quarter is wrong: {p.quarter}, expected 2") return False # Check freqstr if p.freqstr == 'M': f_print_success(f"freqstr is correct: {p.freqstr}") else: f_print_error(f"freqstr is wrong: {p.freqstr}, expected 'M'") return False # Test daily period with more properties p2 = pandasCore.Period('2020-06-15', 'D') f_print_info(f"Daily period: {p2}") f_print_info(f" year={p2.year}, month={p2.month}, day={p2.day}") f_print_info(f" dayofweek={p2.dayofweek}, dayofyear={p2.dayofyear}") .. _example-period-month-2: .. dropdown:: month (test_period.py:75) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 65 :emphasize-lines: 11 p = pandasCore.Period('2020-06', 'M') # Check year if p.year == 2020: f_print_success(f"year is correct: {p.year}") else: f_print_error(f"year is wrong: {p.year}, expected 2020") return False # Check month if p.month == 6: f_print_success(f"month is correct: {p.month}") else: f_print_error(f"month is wrong: {p.month}, expected 6") return False # Check quarter if p.quarter == 2: f_print_success(f"quarter is correct: {p.quarter}") else: f_print_error(f"quarter is wrong: {p.quarter}, expected 2") .. _example-period-ordinal-3: .. dropdown:: ordinal (test_periodindex.py:118) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 108 :emphasize-lines: 11 def test_shift(): """Test shift method""" f_print_header("Test: shift") pi = pandasCore.PeriodIndex([0, 1, 2], freq="D") shifted = pi.shift(1) expected = [1, 2, 3] ctx.assert_list_equal(expected, [p.ordinal for p in shifted.tolist()], "shift by 1") shifted_neg = pi.shift(-1) expected_neg = [-1, 0, 1] ctx.assert_list_equal(expected_neg, [p.ordinal for p in shifted_neg.tolist()], "shift by -1") def test_strftime(): """Test strftime method""" f_print_header("Test: strftime") .. _example-period-quarter-4: .. dropdown:: quarter (test_period.py:82) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 72 :emphasize-lines: 11 return False # Check month if p.month == 6: f_print_success(f"month is correct: {p.month}") else: f_print_error(f"month is wrong: {p.month}, expected 6") return False # Check quarter if p.quarter == 2: f_print_success(f"quarter is correct: {p.quarter}") else: f_print_error(f"quarter is wrong: {p.quarter}, expected 2") return False # Check freqstr if p.freqstr == 'M': f_print_success(f"freqstr is correct: {p.freqstr}") else: f_print_error(f"freqstr is wrong: {p.freqstr}, expected 'M'") .. _example-period-start_time-5: .. dropdown:: start_time (test_period.py:239) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 229 :emphasize-lines: 11 f_print_success(f"Start timestamp year/month correct: {ts_start.year}-{ts_start.month}") else: f_print_error(f"Start timestamp year/month wrong") return False # Convert to timestamp (end) ts_end = p.to_timestamp(how='end') f_print_success(f"to_timestamp(how='end'): {ts_end}") # Check start_time and end_time properties f_print_info(f"start_time: {p.start_time}") f_print_info(f"end_time: {p.end_time}") return True except Exception as e: f_print_error(f"Exception: {e}") return False def test_period_arithmetic(): .. _example-period-year-6: .. dropdown:: year (test_period.py:68) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 58 :emphasize-lines: 11 def test_period_properties(): """Test Period component properties""" f_print_header("Test: Period Properties") try: # Test monthly period p = pandasCore.Period('2020-06', 'M') # Check year if p.year == 2020: f_print_success(f"year is correct: {p.year}") else: f_print_error(f"year is wrong: {p.year}, expected 2020") return False # Check month if p.month == 6: f_print_success(f"month is correct: {p.month}") else: f_print_error(f"month is wrong: {p.month}, expected 6") .. _example-period-dunder-initdunder--7: .. dropdown:: __init__ (test_period.py:33) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 23 :emphasize-lines: 11 import pandasCore import pandas as pd def test_period_construction(): """Test Period construction from various inputs""" f_print_header("Test: Period Construction") try: # Test from period string and frequency p1 = pandasCore.Period('2020-01', 'M') f_print_success(f"Created Period from string: {p1}") # Test from ordinal and frequency p2 = pandasCore.Period(0, 'D') f_print_success(f"Created Period from ordinal: {p2}") # Test from year/month components p3 = pandasCore.Period(year=2020, month=6, day=15, freq='D') f_print_success(f"Created Period from components: {p3}") .. _example-period-asfreq-8: .. dropdown:: asfreq (test_period.py:149) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 139 :emphasize-lines: 11 def test_period_asfreq(): """Test Period.asfreq() method""" f_print_header("Test: Period.asfreq()") try: # Create monthly period p = pandasCore.Period('2020-01', 'M') f_print_info(f"Original period: {p}") # Convert to daily frequency (end of month) p_day_end = p.asfreq('D', 'E') f_print_success(f"asfreq('D', 'E'): {p_day_end}") # The end of January 2020 should be day 31 if p_day_end.day == 31: f_print_success(f"End of month day is correct: {p_day_end.day}") else: f_print_error(f"End of month day is wrong: {p_day_end.day}, expected 31") return False # Convert to daily frequency (start of month) .. _example-period-to_timestamp-9: .. dropdown:: to_timestamp (test_period.py:224) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 214 :emphasize-lines: 11 def test_period_to_timestamp(): """Test Period.to_timestamp() method""" f_print_header("Test: Period.to_timestamp()") try: p = pandasCore.Period('2020-01', 'M') f_print_info(f"Original period: {p}") # Convert to timestamp (start) ts_start = p.to_timestamp(how='start') f_print_success(f"to_timestamp(how='start'): {ts_start}") # Verify year and month if ts_start.year == 2020 and ts_start.month == 1: f_print_success(f"Start timestamp year/month correct: {ts_start.year}-{ts_start.month}") else: f_print_error(f"Start timestamp year/month wrong") return False # Convert to timestamp (end) .. _example-period-strftime-10: .. dropdown:: strftime (test_period.py:189) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 179 :emphasize-lines: 11 def test_period_strftime(): """Test Period.strftime() method""" f_print_header("Test: Period.strftime()") try: p = pandasCore.Period('2020-06-15', 'D') # Test various format strings result1 = p.strftime('%Y-%m-%d') f_print_success(f"strftime('%Y-%m-%d'): {result1}") if result1 == '2020-06-15': f_print_success("Format '%Y-%m-%d' is correct") else: f_print_error(f"Format '%Y-%m-%d' is wrong: {result1}") return False result2 = p.strftime('%Y/%m') f_print_success(f"strftime('%Y/%m'): {result2}") if result2 == '2020/06':