From 8169e4ecf62c21b0338c3529c6803cb8b7a460a1 Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Thu, 15 Aug 2024 23:39:27 +0530 Subject: [PATCH 01/14] Fix docstrings for pandas.Period.year SA01 --- ci/code_checks.sh | 1 - pandas/_libs/tslibs/period.pyx | 42 ++++++++++++++++++++++++++++++++-- 2 files changed, 40 insertions(+), 3 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 50cea056b9204..dbfe0230d835c 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -79,7 +79,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.Period.ordinal GL08" \ -i "pandas.Period.strftime PR01,SA01" \ -i "pandas.Period.to_timestamp SA01" \ - -i "pandas.Period.year SA01" \ -i "pandas.PeriodDtype SA01" \ -i "pandas.PeriodDtype.freq SA01" \ -i "pandas.PeriodIndex.day SA01" \ diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 84d9b57340ed4..2130a10d0f724 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2038,11 +2038,49 @@ cdef class _Period(PeriodMixin): """ Return the year this Period falls on. + Returns + ------- + int + The year (e.g., 2023) + + See Also + -------- + period.month : Get the month of the year on the given Period. + period.day : Return the day of the month the Period falls on. + + Notes + ----- + The year is based on the `ordinal` and `base` attributes of the Period. + Examples -------- - >>> period = pd.Period('2022-01', 'M') + Create a Period object for January 2023 and get the year: + + >>> period = pd.Period('2023-01', 'M') >>> period.year - 2022 + 2023 + + Create a Period object for 01 January 2023 and get the year: + >>> period = pd.Period('2023', 'D') +        >>> period.year +        2023 + + Get the year for a period representing a quarter: + + >>> period = pd.Period('2023Q2', 'Q') + >>> period.year + 2023 + + Handle a case where the Period object is empty, which results in `NaN`: + + >>> period = pd.Period('nan', 'M') + >>> period.month + nan + + Period object with an invalid format: + + >>> period = pd.Period('invalid', 'M') + # Will raise an DateParseError """ base = self._dtype._dtype_code return pyear(self.ordinal, base) From cde723f06927acf41f1fb7d8745306d93c84689f Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Fri, 16 Aug 2024 00:02:24 +0530 Subject: [PATCH 02/14] Fix docstrings for pandas.Period.year SA01 Validate Docstrings err --- pandas/_libs/tslibs/period.pyx | 1 - 1 file changed, 1 deletion(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 2130a10d0f724..45044888d435d 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2041,7 +2041,6 @@ cdef class _Period(PeriodMixin): Returns ------- int - The year (e.g., 2023) See Also -------- From f52c61080a331597197711465742ace1bdfcd1dd Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Fri, 16 Aug 2024 00:38:12 +0530 Subject: [PATCH 03/14] Fix docstrings for pandas.Period.year SA01 Validate Docstrings err --- pandas/_libs/tslibs/period.pyx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 45044888d435d..cdeca432ffc91 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2044,7 +2044,7 @@ cdef class _Period(PeriodMixin): See Also -------- - period.month : Get the month of the year on the given Period. + period.month : Get the month of the year for the given Period. period.day : Return the day of the month the Period falls on. Notes @@ -2060,9 +2060,10 @@ cdef class _Period(PeriodMixin): 2023 Create a Period object for 01 January 2023 and get the year: + >>> period = pd.Period('2023', 'D') -        >>> period.year -        2023 + >>> period.year + 2023 Get the year for a period representing a quarter: @@ -2073,13 +2074,13 @@ cdef class _Period(PeriodMixin): Handle a case where the Period object is empty, which results in `NaN`: >>> period = pd.Period('nan', 'M') - >>> period.month + >>> period.year nan Period object with an invalid format: >>> period = pd.Period('invalid', 'M') - # Will raise an DateParseError + # Will raise a DateParseError """ base = self._dtype._dtype_code return pyear(self.ordinal, base) From b966845638a89b76dd03909dd1cd6f733be155cf Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Fri, 16 Aug 2024 20:11:32 +0530 Subject: [PATCH 04/14] Fix docstrings for pandas.timestamps SA01 PR01 --- ci/code_checks.sh | 16 -- pandas/_libs/tslibs/timestamps.pyx | 261 ++++++++++++++++++++++++++++- 2 files changed, 254 insertions(+), 23 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index dbfe0230d835c..a5ea2955d3755 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -180,36 +180,20 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.TimedeltaIndex.nanoseconds SA01" \ -i "pandas.TimedeltaIndex.seconds SA01" \ -i "pandas.TimedeltaIndex.to_pytimedelta RT03,SA01" \ - -i "pandas.Timestamp.combine PR01,SA01" \ - -i "pandas.Timestamp.ctime SA01" \ - -i "pandas.Timestamp.date SA01" \ -i "pandas.Timestamp.day GL08" \ -i "pandas.Timestamp.fold GL08" \ - -i "pandas.Timestamp.fromordinal SA01" \ - -i "pandas.Timestamp.fromtimestamp PR01,SA01" \ -i "pandas.Timestamp.hour GL08" \ -i "pandas.Timestamp.max PR02" \ -i "pandas.Timestamp.microsecond GL08" \ -i "pandas.Timestamp.min PR02" \ -i "pandas.Timestamp.minute GL08" \ -i "pandas.Timestamp.month GL08" \ - -i "pandas.Timestamp.month_name SA01" \ -i "pandas.Timestamp.nanosecond GL08" \ - -i "pandas.Timestamp.normalize SA01" \ - -i "pandas.Timestamp.quarter SA01" \ - -i "pandas.Timestamp.replace PR07,SA01" \ -i "pandas.Timestamp.resolution PR02" \ -i "pandas.Timestamp.second GL08" \ -i "pandas.Timestamp.strptime PR01,SA01" \ - -i "pandas.Timestamp.timestamp SA01" \ - -i "pandas.Timestamp.timetuple SA01" \ -i "pandas.Timestamp.timetz SA01" \ -i "pandas.Timestamp.to_datetime64 SA01" \ - -i "pandas.Timestamp.to_julian_date SA01" \ - -i "pandas.Timestamp.to_numpy PR01" \ - -i "pandas.Timestamp.to_period PR01,SA01" \ - -i "pandas.Timestamp.today SA01" \ - -i "pandas.Timestamp.toordinal SA01" \ -i "pandas.Timestamp.tzinfo GL08" \ -i "pandas.Timestamp.value GL08" \ -i "pandas.Timestamp.year GL08" \ diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 47e5af14460a8..e84dadf02ace2 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -815,6 +815,11 @@ cdef class _Timestamp(ABCTimestamp): """ Return the month name of the Timestamp with specified locale. + This method returns the full name of the month corresponding to the + `Timestamp`, such as 'January', 'February', etc. The month name can + be returned in a specified locale if provided; otherwise, it defaults + to the English locale. + Parameters ---------- locale : str, default None (English locale) @@ -823,9 +828,18 @@ cdef class _Timestamp(ABCTimestamp): Returns ------- str + The full month name as a string. + + See Also + -------- + pandas.Timestamp.day_name : Returns the name of the day of the week. + pandas.Timestamp.strftime : Returns a formatted string representation of the Timestamp. + datetime.datetime.strftime : Returns a string representing the date and time, controlled by an explicit format string. Examples -------- + Get the month name in English (default): + >>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651') >>> ts.month_name() 'March' @@ -912,17 +926,40 @@ cdef class _Timestamp(ABCTimestamp): @property def quarter(self) -> int: """ - Return the quarter of the year. + Return the quarter of the year for the `Timestamp`. + + This property returns an integer representing the quarter of the year in + which the `Timestamp` falls. The quarters are defined as follows: + - Q1: January 1 to March 31 + - Q2: April 1 to June 30 + - Q3: July 1 to September 30 + - Q4: October 1 to December 31 Returns ------- int + The quarter of the year (1 through 4). + + See Also + -------- + pandas.Timestamp.month : Returns the month of the `Timestamp`. + pandas.Timestamp.year : Returns the year of the `Timestamp`. + pandas.Timestamp.is_quarter_end : Boolean property indicating if the `Timestamp` is at the end of a quarter. + pandas.Timestamp.is_quarter_start : Boolean property indicating if the `Timestamp` is at the start of a quarter. Examples -------- + Get the quarter for a `Timestamp`: + >>> ts = pd.Timestamp(2020, 3, 14) >>> ts.quarter 1 + + For a `Timestamp` in the fourth quarter: + + >>> ts = pd.Timestamp(2020, 10, 14) + >>> ts.quarter + 4 """ return ((self.month - 1) // 3) + 1 @@ -977,6 +1014,21 @@ cdef class _Timestamp(ABCTimestamp): """ Normalize Timestamp to midnight, preserving tz information. + This method sets the time component of the `Timestamp` to midnight (00:00:00), + while preserving the date and time zone information. It is useful when you + need to standardize the time across different `Timestamp` objects without + altering the time zone or the date. + + Returns + ------- + Timestamp + + See Also + -------- + pandas.Timestamp.floor : Round down the `Timestamp` to the nearest specified frequency. + pandas.Timestamp.ceil : Round up the `Timestamp` to the nearest specified frequency. + pandas.Timestamp.round : Round the `Timestamp` to the nearest specified frequency. + Examples -------- >>> ts = pd.Timestamp(2020, 3, 14, 15, 30) @@ -1212,6 +1264,23 @@ cdef class _Timestamp(ABCTimestamp): """ Return POSIX timestamp as float. + This method converts the `Timestamp` object to a POSIX timestamp, which is + the number of seconds since the Unix epoch (January 1, 1970). The returned + value is a floating-point number, where the integer part represents the + seconds, and the fractional part represents the microseconds. + + Returns + ------- + float + The POSIX timestamp representation of the `Timestamp` object. + + See Also + -------- + pandas.Timestamp.fromtimestamp : Construct a `Timestamp` from a POSIX timestamp. + datetime.datetime.timestamp : Equivalent method from the `datetime` module. + pandas.Timestamp.to_pydatetime : Convert the `Timestamp` to a `datetime` object. + pandas.Timestamp.to_datetime64 : Convert the `Timestamp` to a `numpy.datetime64` object. + Examples -------- >>> ts = pd.Timestamp('2020-03-14T15:32:52.192548') @@ -1298,6 +1367,15 @@ cdef class _Timestamp(ABCTimestamp): copy parameters are available here only for compatibility. Their values will not affect the return value. + Parameters + ---------- + dtype : dtype, optional + Data type of the output, ignored in this method as the return type + is always `numpy.datetime64`. + copy : bool, default False + Whether to ensure that the returned value is a new object. This + parameter is also ignored as the method does not support copying. + Returns ------- numpy.datetime64 @@ -1327,6 +1405,23 @@ cdef class _Timestamp(ABCTimestamp): """ Return an period of which this timestamp is an observation. + This method converts the given Timestamp to a Period object, + which represents a span of time,such as a year, month, etc., + based on the specified frequency. + + Parameters + ---------- + freq : str, optional + The frequency string representing the desired period (e.g., 'Y' for yearly, + 'M' for monthly, 'W' for weekly, etc.). If not provided, the default is `None`, + which will infer the frequency. + + See Also + -------- + pandas.Timestamp : Represents a specific timestamp. + pandas.Period : Represents a span of time. + pandas.to_period : Converts an object to a Period. + Examples -------- >>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651') @@ -1464,6 +1559,11 @@ class Timestamp(_Timestamp): """ Construct a timestamp from a a proleptic Gregorian ordinal. + This method creates a `Timestamp` object corresponding to the given + proleptic Gregorian ordinal, which is a count of days from January 1, + 0001 (using the proleptic Gregorian calendar). The time part of the + `Timestamp` is set to midnight (00:00:00) by default. + Parameters ---------- ordinal : int @@ -1471,14 +1571,31 @@ class Timestamp(_Timestamp): tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None Time zone for the Timestamp. + Returns + ------- + Timestamp + A `Timestamp` object representing the specified ordinal date. + Notes ----- By definition there cannot be any tz info on the ordinal itself. + See Also + -------- + pandas.Timestamp : Represents a single timestamp, similar to `datetime`. + pandas.to_datetime : Converts various types of data to datetime. + Examples -------- + Convert an ordinal to a `Timestamp`: + >>> pd.Timestamp.fromordinal(737425) Timestamp('2020-01-01 00:00:00') + + Create a `Timestamp` from an ordinal with timezone information: + + >>> pd.Timestamp.fromordinal(737425, tz='UTC') + Timestamp('2020-01-01 00:00:00+0000', tz='UTC') """ return cls(datetime.fromordinal(ordinal), tz=tz) @@ -1529,6 +1646,12 @@ class Timestamp(_Timestamp): tz : str or timezone object, default None Timezone to localize to. + See Also + -------- + datetime.datetime.today : Returns the current local date. + pandas.Timestamp.now : Returns the current time with an option to specify timezone. + pandas.Timestamp : A class representing a specific timestamp. + Examples -------- >>> pd.Timestamp.today() # doctest: +SKIP @@ -1621,16 +1744,43 @@ class Timestamp(_Timestamp): @classmethod def fromtimestamp(cls, ts, tz=None): """ - Timestamp.fromtimestamp(ts) + Create a `Timestamp` object from a POSIX timestamp. + + This method converts a POSIX timestamp (the number of seconds since + January 1, 1970, 00:00:00 UTC) into a `Timestamp` object. The resulting + `Timestamp` can be localized to a specific time zone if provided. - Transform timestamp[, tz] to tz's local time from POSIX timestamp. + Parameters + ---------- + ts : float + The POSIX timestamp to convert, representing seconds since + the epoch (1970-01-01 00:00:00 UTC). + tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile, or None, optional + Time zone for the `Timestamp`. If not provided, the `Timestamp` will + be timezone-naive (i.e., without time zone information). + + Returns + ------- + Timestamp + A `Timestamp` object representing the given POSIX timestamp. + + See Also + -------- + pandas.Timestamp : Represents a single timestamp, similar to `datetime`. + pandas.to_datetime : Converts various types of data to datetime. + datetime.datetime.fromtimestamp : Returns a datetime object from a POSIX timestamp. Examples -------- + Convert a POSIX timestamp to a `Timestamp`: + >>> pd.Timestamp.fromtimestamp(1584199972) # doctest: +SKIP Timestamp('2020-03-14 15:32:52') - Note that the output may change depending on your local time. + Note that the output may change depending on your local time and time zone: + + >>> pd.Timestamp.fromtimestamp(1584199972, tz='UTC') # doctest: +SKIP + Timestamp('2020-03-14 15:32:52+0000', tz='UTC') """ tz = maybe_get_tz(tz) return cls(datetime.fromtimestamp(ts, tz)) @@ -1673,7 +1823,25 @@ class Timestamp(_Timestamp): def ctime(self): """ - Return ctime() style string. + Return a ctime() style string representing the Timestamp. + + This method returns a string representing the date and time + in the format returned by the standard library's `time.ctime()` + function, which is typically in the form 'Day Mon DD HH:MM:SS YYYY'. + + If the `Timestamp` is outside the range supported by Python's + standard library, a `NotImplementedError` is raised. + + Returns + ------- + str + A string representing the Timestamp in ctime format. + + See Also + -------- + time.ctime : Return a string representing time in ctime format. + pandas.Timestamp : Represents a single timestamp, similar to `datetime`. + datetime.datetime.ctime : Return a ctime style string from a datetime object. Examples -------- @@ -1698,10 +1866,25 @@ class Timestamp(_Timestamp): def date(self): """ - Return date object with same year, month and day. + Return a `datetime.date` object with the same year, month, and day as the Timestamp. + + This method extracts the date component from the `Timestamp` and returns + it as a `datetime.date` object, discarding the time information. + + Returns + ------- + datetime.date + The date part of the `Timestamp`. + + See Also + -------- + pandas.Timestamp : Represents a single timestamp, similar to `datetime`. + datetime.datetime.date : Extract the date component from a `datetime` object. Examples -------- + Extract the date from a Timestamp: + >>> ts = pd.Timestamp('2023-01-01 10:00:00.00') >>> ts Timestamp('2023-01-01 10:00:00') @@ -1879,6 +2062,17 @@ class Timestamp(_Timestamp): """ Return time tuple, compatible with time.localtime(). + This method converts the `Timestamp` into a time tuple, which is compatible + with functions like `time.localtime()`. The time tuple is a named tuple with + attributes such as year, month, day, hour, minute, second, weekday, day of the year, + and daylight savings indicator. + + See Also + -------- + time.localtime : Converts a POSIX timestamp into a time tuple. + pandas.Timestamp : The `Timestamp` object that represents a specific point in time. + datetime.datetime.timetuple : Equivalent method in the `datetime` module. + Examples -------- >>> ts = pd.Timestamp('2023-01-01 10:00:00') @@ -1917,6 +2111,17 @@ class Timestamp(_Timestamp): """ Return proleptic Gregorian ordinal. January 1 of year 1 is day 1. + The proleptic Gregorian ordinal is a continuous count of days since + January 1 of year 1, which is considered day 1. This method converts + the `Timestamp` to its equivalent ordinal number, useful for date arithmetic + and comparison operations. + + See Also + -------- + datetime.datetime.toordinal : Equivalent method in the `datetime` module. + pandas.Timestamp : The `Timestamp` object that represents a specific point in time. + pandas.Timestamp.fromordinal : Create a `Timestamp` from an ordinal. + Examples -------- >>> ts = pd.Timestamp('2023-01-01 10:00:50') @@ -1960,7 +2165,28 @@ class Timestamp(_Timestamp): """ Timestamp.combine(date, time) - Combine date, time into datetime with same date and time fields. + Combine a date and time into a single Timestamp object. + + This method takes a `date` object and a `time` object + and combines them into a single `Timestamp` + that has the same date and time fields. + + Parameters + ---------- + date : datetime.date + The date part of the Timestamp. + time : datetime.time + The time part of the Timestamp. + + Returns + ------- + Timestamp + A new `Timestamp` object representing the combined date and time. + + See Also + -------- + pandas.Timestamp : Represents a single timestamp, similar to `datetime`. + pandas.to_datetime : Converts various types of data to datetime. Examples -------- @@ -2687,18 +2913,33 @@ default 'raise' """ Implements datetime.replace, handles nanoseconds. + This method creates a new `Timestamp` object by replacing the specified + fields with new values. The new `Timestamp` retains the original fields + that are not explicitly replaced. This method handles nanoseconds, and + the `tzinfo` parameter allows for timezone replacement without conversion. + Parameters ---------- year : int, optional + The year to replace. If `None`, the year is not changed. month : int, optional + The month to replace. If `None`, the month is not changed. day : int, optional + The day to replace. If `None`, the day is not changed. hour : int, optional + The hour to replace. If `None`, the hour is not changed. minute : int, optional + The minute to replace. If `None`, the minute is not changed. second : int, optional + The second to replace. If `None`, the second is not changed. microsecond : int, optional + The microsecond to replace. If `None`, the microsecond is not changed. nanosecond : int, optional + The nanosecond to replace. If `None`, the nanosecond is not changed. tzinfo : tz-convertible, optional + The timezone information to replace. If `None`, the timezone is not changed. fold : int, optional + The fold information to replace. If `None`, the fold is not changed. Returns ------- @@ -2827,6 +3068,12 @@ default 'raise' 0 Julian date is noon January 1, 4713 BC. + See Also + -------- + pandas.Timestamp.toordinal : Return proleptic Gregorian ordinal. + pandas.Timestamp.timestamp : Return POSIX timestamp as float. + pandas.Timestamp : Represents a single timestamp. + Examples -------- >>> ts = pd.Timestamp('2020-03-14T15:32:52') From 033ba1240fbf23e7cbea8bfc38abf9da6e165476 Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Sat, 17 Aug 2024 07:57:14 +0530 Subject: [PATCH 05/14] This reverts commit f52c61080a331597197711465742ace1bdfcd1dd. --- pandas/_libs/tslibs/period.pyx | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index cdeca432ffc91..45044888d435d 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2044,7 +2044,7 @@ cdef class _Period(PeriodMixin): See Also -------- - period.month : Get the month of the year for the given Period. + period.month : Get the month of the year on the given Period. period.day : Return the day of the month the Period falls on. Notes @@ -2060,10 +2060,9 @@ cdef class _Period(PeriodMixin): 2023 Create a Period object for 01 January 2023 and get the year: - >>> period = pd.Period('2023', 'D') - >>> period.year - 2023 +        >>> period.year +        2023 Get the year for a period representing a quarter: @@ -2074,13 +2073,13 @@ cdef class _Period(PeriodMixin): Handle a case where the Period object is empty, which results in `NaN`: >>> period = pd.Period('nan', 'M') - >>> period.year + >>> period.month nan Period object with an invalid format: >>> period = pd.Period('invalid', 'M') - # Will raise a DateParseError + # Will raise an DateParseError """ base = self._dtype._dtype_code return pyear(self.ordinal, base) From ce69eda0d5d19651fd3fcb65e179ed0774afbdf1 Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Sat, 17 Aug 2024 07:59:49 +0530 Subject: [PATCH 06/14] Revert "Removed dateparseerror example from period.year" This reverts commit cdf36b2faa6c95848d6210c801ee287f0b7084fd. --- pandas/_libs/tslibs/period.pyx | 5 ----- 1 file changed, 5 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 45044888d435d..10ca078804dea 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2075,11 +2075,6 @@ cdef class _Period(PeriodMixin): >>> period = pd.Period('nan', 'M') >>> period.month nan - - Period object with an invalid format: - - >>> period = pd.Period('invalid', 'M') - # Will raise an DateParseError """ base = self._dtype._dtype_code return pyear(self.ordinal, base) From e327f0fc5d880c819e3572bdc1e185a19ea51d5b Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Sat, 17 Aug 2024 08:09:45 +0530 Subject: [PATCH 07/14] fixing merge conflict --- pandas/_libs/tslibs/period.pyx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 10ca078804dea..4f5dfc75a20bf 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2044,7 +2044,7 @@ cdef class _Period(PeriodMixin): See Also -------- - period.month : Get the month of the year on the given Period. + period.month : Get the month of the year for the given Period. period.day : Return the day of the month the Period falls on. Notes @@ -2060,9 +2060,10 @@ cdef class _Period(PeriodMixin): 2023 Create a Period object for 01 January 2023 and get the year: + >>> period = pd.Period('2023', 'D') -        >>> period.year -        2023 + >>> period.year + 2023 Get the year for a period representing a quarter: @@ -2073,7 +2074,7 @@ cdef class _Period(PeriodMixin): Handle a case where the Period object is empty, which results in `NaN`: >>> period = pd.Period('nan', 'M') - >>> period.month + >>> period.year nan """ base = self._dtype._dtype_code From f64877966e97490875d1ca6f8c659eccd66dd90e Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Sat, 17 Aug 2024 08:34:32 +0530 Subject: [PATCH 08/14] fix pre-commit.ci err --- pandas/_libs/tslibs/timestamps.pyx | 50 ++++++++++++++---------------- 1 file changed, 24 insertions(+), 26 deletions(-) diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index e84dadf02ace2..14d30485c8cd7 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -833,8 +833,8 @@ cdef class _Timestamp(ABCTimestamp): See Also -------- pandas.Timestamp.day_name : Returns the name of the day of the week. - pandas.Timestamp.strftime : Returns a formatted string representation of the Timestamp. - datetime.datetime.strftime : Returns a string representing the date and time, controlled by an explicit format string. + pandas.Timestamp.strftime : Returns a formatted string of the Timestamp. + datetime.datetime.strftime : Returns a string representing the date and time. Examples -------- @@ -928,7 +928,7 @@ cdef class _Timestamp(ABCTimestamp): """ Return the quarter of the year for the `Timestamp`. - This property returns an integer representing the quarter of the year in + This property returns an integer representing the quarter of the year in which the `Timestamp` falls. The quarters are defined as follows: - Q1: January 1 to March 31 - Q2: April 1 to June 30 @@ -944,8 +944,8 @@ cdef class _Timestamp(ABCTimestamp): -------- pandas.Timestamp.month : Returns the month of the `Timestamp`. pandas.Timestamp.year : Returns the year of the `Timestamp`. - pandas.Timestamp.is_quarter_end : Boolean property indicating if the `Timestamp` is at the end of a quarter. - pandas.Timestamp.is_quarter_start : Boolean property indicating if the `Timestamp` is at the start of a quarter. + pandas.Timestamp.is_quarter_end : Returns if `Timestamp` is at the quarter's end. + pandas.Timestamp.is_quarter_start : Indicates if `Timestamp` is at the quarter's start. Examples -------- @@ -1025,9 +1025,9 @@ cdef class _Timestamp(ABCTimestamp): See Also -------- - pandas.Timestamp.floor : Round down the `Timestamp` to the nearest specified frequency. - pandas.Timestamp.ceil : Round up the `Timestamp` to the nearest specified frequency. - pandas.Timestamp.round : Round the `Timestamp` to the nearest specified frequency. + pandas.Timestamp.floor : Rounds `Timestamp` down to the nearest frequency. + pandas.Timestamp.ceil : Rounds `Timestamp` up to the nearest frequency. + pandas.Timestamp.round : Rounds `Timestamp` to the nearest frequency. Examples -------- @@ -1279,7 +1279,7 @@ cdef class _Timestamp(ABCTimestamp): pandas.Timestamp.fromtimestamp : Construct a `Timestamp` from a POSIX timestamp. datetime.datetime.timestamp : Equivalent method from the `datetime` module. pandas.Timestamp.to_pydatetime : Convert the `Timestamp` to a `datetime` object. - pandas.Timestamp.to_datetime64 : Convert the `Timestamp` to a `numpy.datetime64` object. + pandas.Timestamp.to_datetime64 : Converts `Timestamp` to `numpy.datetime64`. Examples -------- @@ -1370,10 +1370,10 @@ cdef class _Timestamp(ABCTimestamp): Parameters ---------- dtype : dtype, optional - Data type of the output, ignored in this method as the return type + Data type of the output, ignored in this method as the return type is always `numpy.datetime64`. copy : bool, default False - Whether to ensure that the returned value is a new object. This + Whether to ensure that the returned value is a new object. This parameter is also ignored as the method does not support copying. Returns @@ -1412,9 +1412,7 @@ cdef class _Timestamp(ABCTimestamp): Parameters ---------- freq : str, optional - The frequency string representing the desired period (e.g., 'Y' for yearly, - 'M' for monthly, 'W' for weekly, etc.). If not provided, the default is `None`, - which will infer the frequency. + Frequency string for the period (e.g., 'Y', 'M', 'W'). Defaults to `None`. See Also -------- @@ -1649,7 +1647,7 @@ class Timestamp(_Timestamp): See Also -------- datetime.datetime.today : Returns the current local date. - pandas.Timestamp.now : Returns the current time with an option to specify timezone. + pandas.Timestamp.now : Returns current time with optional timezone. pandas.Timestamp : A class representing a specific timestamp. Examples @@ -1746,17 +1744,17 @@ class Timestamp(_Timestamp): """ Create a `Timestamp` object from a POSIX timestamp. - This method converts a POSIX timestamp (the number of seconds since - January 1, 1970, 00:00:00 UTC) into a `Timestamp` object. The resulting + This method converts a POSIX timestamp (the number of seconds since + January 1, 1970, 00:00:00 UTC) into a `Timestamp` object. The resulting `Timestamp` can be localized to a specific time zone if provided. Parameters ---------- ts : float - The POSIX timestamp to convert, representing seconds since + The POSIX timestamp to convert, representing seconds since the epoch (1970-01-01 00:00:00 UTC). - tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile, or None, optional - Time zone for the `Timestamp`. If not provided, the `Timestamp` will + tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile, optional + Time zone for the `Timestamp`. If not provided, the `Timestamp` will be timezone-naive (i.e., without time zone information). Returns @@ -1768,7 +1766,7 @@ class Timestamp(_Timestamp): -------- pandas.Timestamp : Represents a single timestamp, similar to `datetime`. pandas.to_datetime : Converts various types of data to datetime. - datetime.datetime.fromtimestamp : Returns a datetime object from a POSIX timestamp. + datetime.datetime.fromtimestamp : Returns a datetime from a POSIX timestamp. Examples -------- @@ -1866,7 +1864,7 @@ class Timestamp(_Timestamp): def date(self): """ - Return a `datetime.date` object with the same year, month, and day as the Timestamp. + Returns `datetime.date` with the same year, month, and day. This method extracts the date component from the `Timestamp` and returns it as a `datetime.date` object, discarding the time information. @@ -2064,13 +2062,13 @@ class Timestamp(_Timestamp): This method converts the `Timestamp` into a time tuple, which is compatible with functions like `time.localtime()`. The time tuple is a named tuple with - attributes such as year, month, day, hour, minute, second, weekday, day of the year, - and daylight savings indicator. + attributes such as year, month, day, hour, minute, second, weekday, + day of the year, and daylight savings indicator. See Also -------- time.localtime : Converts a POSIX timestamp into a time tuple. - pandas.Timestamp : The `Timestamp` object that represents a specific point in time. + pandas.Timestamp : The `Timestamp` that represents a specific point in time. datetime.datetime.timetuple : Equivalent method in the `datetime` module. Examples @@ -2119,7 +2117,7 @@ class Timestamp(_Timestamp): See Also -------- datetime.datetime.toordinal : Equivalent method in the `datetime` module. - pandas.Timestamp : The `Timestamp` object that represents a specific point in time. + pandas.Timestamp : The `Timestamp` that represents a specific point in time. pandas.Timestamp.fromordinal : Create a `Timestamp` from an ordinal. Examples From 1f0ffad0bdcb8ee7435f5c422b2a506efe0d5c3b Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Sat, 17 Aug 2024 08:39:18 +0530 Subject: [PATCH 09/14] fix pre-commit.ci err --- pandas/_libs/tslibs/timestamps.pyx | 2 -- 1 file changed, 2 deletions(-) diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 14d30485c8cd7..6541e952a7420 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -944,8 +944,6 @@ cdef class _Timestamp(ABCTimestamp): -------- pandas.Timestamp.month : Returns the month of the `Timestamp`. pandas.Timestamp.year : Returns the year of the `Timestamp`. - pandas.Timestamp.is_quarter_end : Returns if `Timestamp` is at the quarter's end. - pandas.Timestamp.is_quarter_start : Indicates if `Timestamp` is at the quarter's start. Examples -------- From 80644a8711d8e82dd9e5e975d12e6aeaca34444a Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Sat, 17 Aug 2024 11:40:10 +0530 Subject: [PATCH 10/14] fix Docstring validation err --- pandas/_libs/tslibs/timestamps.pyx | 73 +++++++++++++++++------------- 1 file changed, 42 insertions(+), 31 deletions(-) diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 6541e952a7420..8b4fef6c1ebe4 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -832,8 +832,8 @@ cdef class _Timestamp(ABCTimestamp): See Also -------- - pandas.Timestamp.day_name : Returns the name of the day of the week. - pandas.Timestamp.strftime : Returns a formatted string of the Timestamp. + Timestamp.day_name : Returns the name of the day of the week. + Timestamp.strftime : Returns a formatted string of the Timestamp. datetime.datetime.strftime : Returns a string representing the date and time. Examples @@ -942,8 +942,8 @@ cdef class _Timestamp(ABCTimestamp): See Also -------- - pandas.Timestamp.month : Returns the month of the `Timestamp`. - pandas.Timestamp.year : Returns the year of the `Timestamp`. + Timestamp.month : Returns the month of the `Timestamp`. + Timestamp.year : Returns the year of the `Timestamp`. Examples -------- @@ -1023,9 +1023,9 @@ cdef class _Timestamp(ABCTimestamp): See Also -------- - pandas.Timestamp.floor : Rounds `Timestamp` down to the nearest frequency. - pandas.Timestamp.ceil : Rounds `Timestamp` up to the nearest frequency. - pandas.Timestamp.round : Rounds `Timestamp` to the nearest frequency. + Timestamp.floor : Rounds `Timestamp` down to the nearest frequency. + Timestamp.ceil : Rounds `Timestamp` up to the nearest frequency. + Timestamp.round : Rounds `Timestamp` to the nearest frequency. Examples -------- @@ -1274,10 +1274,10 @@ cdef class _Timestamp(ABCTimestamp): See Also -------- - pandas.Timestamp.fromtimestamp : Construct a `Timestamp` from a POSIX timestamp. + Timestamp.fromtimestamp : Construct a `Timestamp` from a POSIX timestamp. datetime.datetime.timestamp : Equivalent method from the `datetime` module. - pandas.Timestamp.to_pydatetime : Convert the `Timestamp` to a `datetime` object. - pandas.Timestamp.to_datetime64 : Converts `Timestamp` to `numpy.datetime64`. + Timestamp.to_pydatetime : Convert the `Timestamp` to a `datetime` object. + Timestamp.to_datetime64 : Converts `Timestamp` to `numpy.datetime64`. Examples -------- @@ -1414,9 +1414,9 @@ cdef class _Timestamp(ABCTimestamp): See Also -------- - pandas.Timestamp : Represents a specific timestamp. - pandas.Period : Represents a span of time. - pandas.to_period : Converts an object to a Period. + Timestamp : Represents a specific timestamp. + Period : Represents a span of time. + to_period : Converts an object to a Period. Examples -------- @@ -1572,15 +1572,15 @@ class Timestamp(_Timestamp): Timestamp A `Timestamp` object representing the specified ordinal date. + See Also + -------- + Timestamp : Represents a single timestamp, similar to `datetime`. + to_datetime : Converts various types of data to datetime. + Notes ----- By definition there cannot be any tz info on the ordinal itself. - See Also - -------- - pandas.Timestamp : Represents a single timestamp, similar to `datetime`. - pandas.to_datetime : Converts various types of data to datetime. - Examples -------- Convert an ordinal to a `Timestamp`: @@ -1762,8 +1762,8 @@ class Timestamp(_Timestamp): See Also -------- - pandas.Timestamp : Represents a single timestamp, similar to `datetime`. - pandas.to_datetime : Converts various types of data to datetime. + Timestamp : Represents a single timestamp, similar to `datetime`. + to_datetime : Converts various types of data to datetime. datetime.datetime.fromtimestamp : Returns a datetime from a POSIX timestamp. Examples @@ -1836,7 +1836,7 @@ class Timestamp(_Timestamp): See Also -------- time.ctime : Return a string representing time in ctime format. - pandas.Timestamp : Represents a single timestamp, similar to `datetime`. + Timestamp : Represents a single timestamp, similar to `datetime`. datetime.datetime.ctime : Return a ctime style string from a datetime object. Examples @@ -1874,7 +1874,7 @@ class Timestamp(_Timestamp): See Also -------- - pandas.Timestamp : Represents a single timestamp, similar to `datetime`. + Timestamp : Represents a single timestamp, similar to `datetime`. datetime.datetime.date : Extract the date component from a `datetime` object. Examples @@ -2066,7 +2066,7 @@ class Timestamp(_Timestamp): See Also -------- time.localtime : Converts a POSIX timestamp into a time tuple. - pandas.Timestamp : The `Timestamp` that represents a specific point in time. + Timestamp : The `Timestamp` that represents a specific point in time. datetime.datetime.timetuple : Equivalent method in the `datetime` module. Examples @@ -2115,8 +2115,8 @@ class Timestamp(_Timestamp): See Also -------- datetime.datetime.toordinal : Equivalent method in the `datetime` module. - pandas.Timestamp : The `Timestamp` that represents a specific point in time. - pandas.Timestamp.fromordinal : Create a `Timestamp` from an ordinal. + Timestamp : The `Timestamp` that represents a specific point in time. + Timestamp.fromordinal : Create a `Timestamp` from an ordinal. Examples -------- @@ -2181,8 +2181,8 @@ class Timestamp(_Timestamp): See Also -------- - pandas.Timestamp : Represents a single timestamp, similar to `datetime`. - pandas.to_datetime : Converts various types of data to datetime. + Timestamp : Represents a single timestamp, similar to `datetime`. + to_datetime : Converts various types of data to datetime. Examples -------- @@ -2939,7 +2939,18 @@ default 'raise' Returns ------- - Timestamp with fields replaced + Timestamp + A new `Timestamp` object with the specified fields replaced. + + See Also + -------- + Timestamp : Represents a single timestamp, similar to `datetime`. + to_datetime : Converts various types of data to datetime. + + Notes + ----- + The `replace` method does not perform timezone conversions. If you need + to convert the timezone, use the `tz_convert` method instead. Examples -------- @@ -3066,9 +3077,9 @@ default 'raise' See Also -------- - pandas.Timestamp.toordinal : Return proleptic Gregorian ordinal. - pandas.Timestamp.timestamp : Return POSIX timestamp as float. - pandas.Timestamp : Represents a single timestamp. + Timestamp.toordinal : Return proleptic Gregorian ordinal. + Timestamp.timestamp : Return POSIX timestamp as float. + Timestamp : Represents a single timestamp. Examples -------- From 1cfb52208469f18345bcdbc8a7b2c5b53ab81307 Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Sat, 17 Aug 2024 12:05:43 +0530 Subject: [PATCH 11/14] fix Docstring validation err --- pandas/_libs/tslibs/timestamps.pyx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 8b4fef6c1ebe4..494dbecfe86b5 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -1645,8 +1645,8 @@ class Timestamp(_Timestamp): See Also -------- datetime.datetime.today : Returns the current local date. - pandas.Timestamp.now : Returns current time with optional timezone. - pandas.Timestamp : A class representing a specific timestamp. + Timestamp.now : Returns current time with optional timezone. + Timestamp : A class representing a specific timestamp. Examples -------- From a72c94c6c19501ed653c60804aaf0fbc14ffda1b Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Sat, 17 Aug 2024 15:21:35 +0530 Subject: [PATCH 12/14] fix Docstring validation err --- pandas/_libs/tslibs/nattype.pyx | 206 +++++++++++++++++++++++++++++--- 1 file changed, 191 insertions(+), 15 deletions(-) diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 547f95badab53..3533280c6e675 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -244,16 +244,24 @@ cdef class _NaT(datetime): def to_numpy(self, dtype=None, copy=False) -> np.datetime64 | np.timedelta64: """ - Convert the Timestamp to a NumPy datetime64 or timedelta64. + Convert the Timestamp to a NumPy datetime64. - With the default 'dtype', this is an alias method for `NaT.to_datetime64()`. - - The copy parameter is available here only for compatibility. Its value + This is an alias method for `Timestamp.to_datetime64()`. The dtype and + copy parameters are available here only for compatibility. Their values will not affect the return value. + Parameters + ---------- + dtype : dtype, optional + Data type of the output, ignored in this method as the return type + is always `numpy.datetime64`. + copy : bool, default False + Whether to ensure that the returned value is a new object. This + parameter is also ignored as the method does not support copying. + Returns ------- - numpy.datetime64 or numpy.timedelta64 + numpy.datetime64 See Also -------- @@ -269,9 +277,6 @@ cdef class _NaT(datetime): >>> pd.NaT.to_numpy() numpy.datetime64('NaT') - - >>> pd.NaT.to_numpy("m8[ns]") - numpy.timedelta64('NaT','ns') """ if dtype is not None: # GH#44460 @@ -476,6 +481,11 @@ class NaTType(_NaT): """ Return the month name of the Timestamp with specified locale. + This method returns the full name of the month corresponding to the + `Timestamp`, such as 'January', 'February', etc. The month name can + be returned in a specified locale if provided; otherwise, it defaults + to the English locale. + Parameters ---------- locale : str, default None (English locale) @@ -484,9 +494,18 @@ class NaTType(_NaT): Returns ------- str + The full month name as a string. + + See Also + -------- + Timestamp.day_name : Returns the name of the day of the week. + Timestamp.strftime : Returns a formatted string of the Timestamp. + datetime.datetime.strftime : Returns a string representing the date and time. Examples -------- + Get the month name in English (default): + >>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651') >>> ts.month_name() 'March' @@ -581,10 +600,25 @@ class NaTType(_NaT): date = _make_nat_func( "date", """ - Return date object with same year, month and day. + Returns `datetime.date` with the same year, month, and day. + + This method extracts the date component from the `Timestamp` and returns + it as a `datetime.date` object, discarding the time information. + + Returns + ------- + datetime.date + The date part of the `Timestamp`. + + See Also + -------- + Timestamp : Represents a single timestamp, similar to `datetime`. + datetime.datetime.date : Extract the date component from a `datetime` object. Examples -------- + Extract the date from a Timestamp: + >>> ts = pd.Timestamp('2023-01-01 10:00:00.00') >>> ts Timestamp('2023-01-01 10:00:00') @@ -704,6 +738,17 @@ class NaTType(_NaT): """ Return time tuple, compatible with time.localtime(). + This method converts the `Timestamp` into a time tuple, which is compatible + with functions like `time.localtime()`. The time tuple is a named tuple with + attributes such as year, month, day, hour, minute, second, weekday, + day of the year, and daylight savings indicator. + + See Also + -------- + time.localtime : Converts a POSIX timestamp into a time tuple. + Timestamp : The `Timestamp` that represents a specific point in time. + datetime.datetime.timetuple : Equivalent method in the `datetime` module. + Examples -------- >>> ts = pd.Timestamp('2023-01-01 10:00:00') @@ -733,6 +778,17 @@ class NaTType(_NaT): """ Return proleptic Gregorian ordinal. January 1 of year 1 is day 1. + The proleptic Gregorian ordinal is a continuous count of days since + January 1 of year 1, which is considered day 1. This method converts + the `Timestamp` to its equivalent ordinal number, useful for date arithmetic + and comparison operations. + + See Also + -------- + datetime.datetime.toordinal : Equivalent method in the `datetime` module. + Timestamp : The `Timestamp` that represents a specific point in time. + Timestamp.fromordinal : Create a `Timestamp` from an ordinal. + Examples -------- >>> ts = pd.Timestamp('2023-01-01 10:00:50') @@ -745,7 +801,25 @@ class NaTType(_NaT): ctime = _make_error_func( "ctime", """ - Return ctime() style string. + Return a ctime() style string representing the Timestamp. + + This method returns a string representing the date and time + in the format returned by the standard library's `time.ctime()` + function, which is typically in the form 'Day Mon DD HH:MM:SS YYYY'. + + If the `Timestamp` is outside the range supported by Python's + standard library, a `NotImplementedError` is raised. + + Returns + ------- + str + A string representing the Timestamp in ctime format. + + See Also + -------- + time.ctime : Return a string representing time in ctime format. + Timestamp : Represents a single timestamp, similar to `datetime`. + datetime.datetime.ctime : Return a ctime style string from a datetime object. Examples -------- @@ -834,16 +908,43 @@ class NaTType(_NaT): fromtimestamp = _make_error_func( "fromtimestamp", """ - Timestamp.fromtimestamp(ts) + Create a `Timestamp` object from a POSIX timestamp. + + This method converts a POSIX timestamp (the number of seconds since + January 1, 1970, 00:00:00 UTC) into a `Timestamp` object. The resulting + `Timestamp` can be localized to a specific time zone if provided. + + Parameters + ---------- + ts : float + The POSIX timestamp to convert, representing seconds since + the epoch (1970-01-01 00:00:00 UTC). + tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile, optional + Time zone for the `Timestamp`. If not provided, the `Timestamp` will + be timezone-naive (i.e., without time zone information). + + Returns + ------- + Timestamp + A `Timestamp` object representing the given POSIX timestamp. - Transform timestamp[, tz] to tz's local time from POSIX timestamp. + See Also + -------- + Timestamp : Represents a single timestamp, similar to `datetime`. + to_datetime : Converts various types of data to datetime. + datetime.datetime.fromtimestamp : Returns a datetime from a POSIX timestamp. Examples -------- + Convert a POSIX timestamp to a `Timestamp`: + >>> pd.Timestamp.fromtimestamp(1584199972) # doctest: +SKIP Timestamp('2020-03-14 15:32:52') - Note that the output may change depending on your local time. + Note that the output may change depending on your local time and time zone: + + >>> pd.Timestamp.fromtimestamp(1584199972, tz='UTC') # doctest: +SKIP + Timestamp('2020-03-14 15:32:52+0000', tz='UTC') """, ) combine = _make_error_func( @@ -851,7 +952,28 @@ class NaTType(_NaT): """ Timestamp.combine(date, time) - Combine date, time into datetime with same date and time fields. + Combine a date and time into a single Timestamp object. + + This method takes a `date` object and a `time` object + and combines them into a single `Timestamp` + that has the same date and time fields. + + Parameters + ---------- + date : datetime.date + The date part of the Timestamp. + time : datetime.time + The time part of the Timestamp. + + Returns + ------- + Timestamp + A new `Timestamp` object representing the combined date and time. + + See Also + -------- + Timestamp : Represents a single timestamp, similar to `datetime`. + to_datetime : Converts various types of data to datetime. Examples -------- @@ -962,6 +1084,11 @@ class NaTType(_NaT): """ Construct a timestamp from a a proleptic Gregorian ordinal. + This method creates a `Timestamp` object corresponding to the given + proleptic Gregorian ordinal, which is a count of days from January 1, + 0001 (using the proleptic Gregorian calendar). The time part of the + `Timestamp` is set to midnight (00:00:00) by default. + Parameters ---------- ordinal : int @@ -969,14 +1096,31 @@ class NaTType(_NaT): tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile or None Time zone for the Timestamp. + Returns + ------- + Timestamp + A `Timestamp` object representing the specified ordinal date. + + See Also + -------- + Timestamp : Represents a single timestamp, similar to `datetime`. + to_datetime : Converts various types of data to datetime. + Notes ----- By definition there cannot be any tz info on the ordinal itself. Examples -------- + Convert an ordinal to a `Timestamp`: + >>> pd.Timestamp.fromordinal(737425) Timestamp('2020-01-01 00:00:00') + + Create a `Timestamp` from an ordinal with timezone information: + + >>> pd.Timestamp.fromordinal(737425, tz='UTC') + Timestamp('2020-01-01 00:00:00+0000', tz='UTC') """, ) @@ -1068,6 +1212,12 @@ class NaTType(_NaT): tz : str or timezone object, default None Timezone to localize to. + See Also + -------- + datetime.datetime.today : Returns the current local date. + Timestamp.now : Returns current time with optional timezone. + Timestamp : A class representing a specific timestamp. + Examples -------- >>> pd.Timestamp.today() # doctest: +SKIP @@ -1518,22 +1668,48 @@ default 'raise' """ Implements datetime.replace, handles nanoseconds. + This method creates a new `Timestamp` object by replacing the specified + fields with new values. The new `Timestamp` retains the original fields + that are not explicitly replaced. This method handles nanoseconds, and + the `tzinfo` parameter allows for timezone replacement without conversion. + Parameters ---------- year : int, optional + The year to replace. If `None`, the year is not changed. month : int, optional + The month to replace. If `None`, the month is not changed. day : int, optional + The day to replace. If `None`, the day is not changed. hour : int, optional + The hour to replace. If `None`, the hour is not changed. minute : int, optional + The minute to replace. If `None`, the minute is not changed. second : int, optional + The second to replace. If `None`, the second is not changed. microsecond : int, optional + The microsecond to replace. If `None`, the microsecond is not changed. nanosecond : int, optional + The nanosecond to replace. If `None`, the nanosecond is not changed. tzinfo : tz-convertible, optional + The timezone information to replace. If `None`, the timezone is not changed. fold : int, optional + The fold information to replace. If `None`, the fold is not changed. Returns ------- - Timestamp with fields replaced + Timestamp + A new `Timestamp` object with the specified fields replaced. + + See Also + -------- + Timestamp : Represents a single timestamp, similar to `datetime`. + to_datetime : Converts various types of data to datetime. + + Notes + ----- + The `replace` method does not perform timezone conversions. If you need + to convert the timezone, use the `tz_convert` method instead. Examples -------- From 9e22a8837fa1fd5bd8fc62d35df701d03fa9d28e Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Sat, 17 Aug 2024 16:30:03 +0530 Subject: [PATCH 13/14] fix timestamp Docstring validation err --- pandas/_libs/tslibs/nattype.pyx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 3533280c6e675..f5d671c5c42e9 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -1013,6 +1013,23 @@ class NaTType(_NaT): """ Return POSIX timestamp as float. + This method converts the `Timestamp` object to a POSIX timestamp, which is + the number of seconds since the Unix epoch (January 1, 1970). The returned + value is a floating-point number, where the integer part represents the + seconds, and the fractional part represents the microseconds. + + Returns + ------- + float + The POSIX timestamp representation of the `Timestamp` object. + + See Also + -------- + Timestamp.fromtimestamp : Construct a `Timestamp` from a POSIX timestamp. + datetime.datetime.timestamp : Equivalent method from the `datetime` module. + Timestamp.to_pydatetime : Convert the `Timestamp` to a `datetime` object. + Timestamp.to_datetime64 : Converts `Timestamp` to `numpy.datetime64`. + Examples -------- >>> ts = pd.Timestamp('2020-03-14T15:32:52.192548') From 417b1d98e2d7e9369b00addbe0601414593f3e74 Mon Sep 17 00:00:00 2001 From: uditbaliyan Date: Sat, 17 Aug 2024 17:37:49 +0530 Subject: [PATCH 14/14] pandas/plotting/_matplotlib/core.py:549: error: Unused "type: ignore" comment [unused-ignore] --- pandas/plotting/_matplotlib/core.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/plotting/_matplotlib/core.py b/pandas/plotting/_matplotlib/core.py index fb7d785a94bc4..9a7e563332a42 100644 --- a/pandas/plotting/_matplotlib/core.py +++ b/pandas/plotting/_matplotlib/core.py @@ -546,7 +546,7 @@ def _maybe_right_yaxis(self, ax: Axes, axes_num: int) -> Axes: new_ax.set_yscale("log") elif self.logy == "sym" or self.loglog == "sym": new_ax.set_yscale("symlog") - return new_ax # type: ignore[return-value] + return new_ax @final @cache_readonly