diff --git a/doc/source/reference/arrays.rst b/doc/source/reference/arrays.rst index c6fda85b0486d..38792c46e5f54 100644 --- a/doc/source/reference/arrays.rst +++ b/doc/source/reference/arrays.rst @@ -2,9 +2,9 @@ .. _api.arrays: -============= -pandas arrays -============= +====================================== +pandas arrays, scalars, and data types +====================================== .. currentmodule:: pandas @@ -141,11 +141,11 @@ Methods Timestamp.weekday A collection of timestamps may be stored in a :class:`arrays.DatetimeArray`. -For timezone-aware data, the ``.dtype`` of a ``DatetimeArray`` is a +For timezone-aware data, the ``.dtype`` of a :class:`arrays.DatetimeArray` is a :class:`DatetimeTZDtype`. For timezone-naive data, ``np.dtype("datetime64[ns]")`` is used. -If the data are tz-aware, then every value in the array must have the same timezone. +If the data are timezone-aware, then every value in the array must have the same timezone. .. autosummary:: :toctree: api/ @@ -206,7 +206,7 @@ Methods Timedelta.to_numpy Timedelta.total_seconds -A collection of timedeltas may be stored in a :class:`TimedeltaArray`. +A collection of :class:`Timedelta` may be stored in a :class:`TimedeltaArray`. .. autosummary:: :toctree: api/ @@ -267,8 +267,8 @@ Methods Period.strftime Period.to_timestamp -A collection of timedeltas may be stored in a :class:`arrays.PeriodArray`. -Every period in a ``PeriodArray`` must have the same ``freq``. +A collection of :class:`Period` may be stored in a :class:`arrays.PeriodArray`. +Every period in a :class:`arrays.PeriodArray` must have the same ``freq``. .. autosummary:: :toctree: api/ @@ -383,8 +383,8 @@ Categorical data ---------------- pandas defines a custom data type for representing data that can take only a -limited, fixed set of values. The dtype of a ``Categorical`` can be described by -a :class:`pandas.api.types.CategoricalDtype`. +limited, fixed set of values. The dtype of a :class:`Categorical` can be described by +a :class:`CategoricalDtype`. .. autosummary:: :toctree: api/ @@ -414,7 +414,7 @@ have the categories and integer codes already: Categorical.from_codes -The dtype information is available on the ``Categorical`` +The dtype information is available on the :class:`Categorical` .. autosummary:: :toctree: api/ @@ -425,21 +425,21 @@ The dtype information is available on the ``Categorical`` Categorical.codes ``np.asarray(categorical)`` works by implementing the array interface. Be aware, that this converts -the Categorical back to a NumPy array, so categories and order information is not preserved! +the :class:`Categorical` back to a NumPy array, so categories and order information is not preserved! .. autosummary:: :toctree: api/ Categorical.__array__ -A ``Categorical`` can be stored in a ``Series`` or ``DataFrame``. +A :class:`Categorical` can be stored in a :class:`Series` or :class:`DataFrame`. To create a Series of dtype ``category``, use ``cat = s.astype(dtype)`` or ``Series(..., dtype=dtype)`` where ``dtype`` is either * the string ``'category'`` -* an instance of :class:`~pandas.api.types.CategoricalDtype`. +* an instance of :class:`CategoricalDtype`. -If the Series is of dtype ``CategoricalDtype``, ``Series.cat`` can be used to change the categorical +If the :class:`Series` is of dtype :class:`CategoricalDtype`, ``Series.cat`` can be used to change the categorical data. See :ref:`api.series.cat` for more. .. _api.arrays.sparse: @@ -488,7 +488,7 @@ we recommend using :class:`StringDtype` (with the alias ``"string"``). StringDtype -The ``Series.str`` accessor is available for ``Series`` backed by a :class:`arrays.StringArray`. +The ``Series.str`` accessor is available for :class:`Series` backed by a :class:`arrays.StringArray`. See :ref:`api.series.str` for more. @@ -498,7 +498,7 @@ Boolean data with missing values -------------------------------- The boolean dtype (with the alias ``"boolean"``) provides support for storing -boolean data (True, False values) with missing values, which is not possible +boolean data (``True``, ``False``) with missing values, which is not possible with a bool :class:`numpy.ndarray`. .. autosummary:: diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 6ca43aebed89c..e6a70177463b8 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -623,7 +623,7 @@ class NaTType(_NaT): astimezone = _make_error_func( "astimezone", """ - Convert tz-aware Timestamp to another time zone. + Convert timezone-aware Timestamp to another time zone. Parameters ---------- @@ -1033,7 +1033,7 @@ timedelta}, default 'raise' tz_convert = _make_nat_func( "tz_convert", """ - Convert tz-aware Timestamp to another time zone. + Convert timezone-aware Timestamp to another time zone. Parameters ---------- @@ -1078,7 +1078,7 @@ timedelta}, default 'raise' "tz_localize", """ Convert naive Timestamp to local time zone, or remove - timezone from tz-aware Timestamp. + timezone from timezone-aware Timestamp. Parameters ---------- diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 1df1c9a947e8d..b2ea2e746b44c 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1571,6 +1571,20 @@ cdef class PeriodMixin: @property def end_time(self) -> Timestamp: + """ + Get the Timestamp for the end of the period. + + Returns + ------- + Timestamp + + See Also + -------- + Period.start_time : Return the start Timestamp. + Period.dayofyear : Return the day of year. + Period.daysinmonth : Return the days in that month. + Period.dayofweek : Return the day of the week. + """ return self.to_timestamp(how="end") def _require_matching_freq(self, other, base=False): @@ -1835,11 +1849,17 @@ cdef class _Period(PeriodMixin): @property def year(self) -> int: + """ + Return the year this Period falls on. + """ base = self._dtype._dtype_code return pyear(self.ordinal, base) @property def month(self) -> int: + """ + Return the month this Period falls on. + """ base = self._dtype._dtype_code return pmonth(self.ordinal, base) @@ -1946,6 +1966,32 @@ cdef class _Period(PeriodMixin): @property def weekofyear(self) -> int: + """ + Get the week of the year on the given Period. + + Returns + ------- + int + + See Also + -------- + Period.dayofweek : Get the day component of the Period. + Period.weekday : Get the day component of the Period. + + Examples + -------- + >>> p = pd.Period("2018-03-11", "H") + >>> p.weekofyear + 10 + + >>> p = pd.Period("2018-02-01", "D") + >>> p.weekofyear + 5 + + >>> p = pd.Period("2018-01-06", "D") + >>> p.weekofyear + 1 + """ base = self._dtype._dtype_code return pweek(self.ordinal, base) @@ -2120,6 +2166,9 @@ cdef class _Period(PeriodMixin): @property def quarter(self) -> int: + """ + Return the quarter this Period falls on. + """ base = self._dtype._dtype_code return pquarter(self.ordinal, base) @@ -2225,14 +2274,23 @@ cdef class _Period(PeriodMixin): @property def is_leap_year(self) -> bool: + """ + Return True if the period's year is in a leap year. + """ return bool(is_leapyear(self.year)) @classmethod def now(cls, freq=None): + """ + Return the period of now's date. + """ return Period(datetime.now(), freq=freq) @property def freqstr(self) -> str: + """ + Return a string representation of the frequency. + """ return self.freq.freqstr def __repr__(self) -> str: diff --git a/pandas/_libs/tslibs/timedeltas.pyx b/pandas/_libs/tslibs/timedeltas.pyx index a908eefd41768..02017c5900ca0 100644 --- a/pandas/_libs/tslibs/timedeltas.pyx +++ b/pandas/_libs/tslibs/timedeltas.pyx @@ -886,7 +886,7 @@ cdef class _Timedelta(timedelta): cpdef timedelta to_pytimedelta(_Timedelta self): """ - Convert a pandas Timedelta object into a python timedelta object. + Convert a pandas Timedelta object into a python ``datetime.timedelta`` object. Timedelta objects are internally saved as numpy datetime64[ns] dtype. Use to_pytimedelta() to convert to object dtype. diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 03ee62e59aa3d..b13b77506ecc7 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -740,7 +740,7 @@ cdef class _Timestamp(ABCTimestamp): def isoformat(self, sep: str = "T", timespec: str = "auto") -> str: """ - Return the time formatted according to ISO. + Return the time formatted according to ISO 8610. The full format looks like 'YYYY-MM-DD HH:MM:SS.mmmmmmnnn'. By default, the fractional part is omitted if self.microsecond == 0 @@ -1749,7 +1749,7 @@ timedelta}, default 'raise' def tz_localize(self, tz, ambiguous='raise', nonexistent='raise'): """ Convert naive Timestamp to local time zone, or remove - timezone from tz-aware Timestamp. + timezone from timezone-aware Timestamp. Parameters ---------- @@ -1852,7 +1852,7 @@ default 'raise' def tz_convert(self, tz): """ - Convert tz-aware Timestamp to another time zone. + Convert timezone-aware Timestamp to another time zone. Parameters ----------