Skip to content

Commit

Permalink
refactor(python): rename dt.seconds to dt.total_seconds (likewise for…
Browse files Browse the repository at this point in the history 
… days, hours, minutes, milliseconds, microseconds, and nanoseconds) for temporal types
  • Loading branch information
@MarcoGorelli
MarcoGorelli committed Nov 1, 2023
1 parent 68956e0 commit 6d6a997
Show file tree
Hide file tree
Showing 10 changed files with 250 additions and 67 deletions.
2 changes: 1 addition & 1 deletion docs/src/python/user-guide/transformations/time-series/rolling.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@

out = df.group_by_dynamic("time", every="1mo", period="1mo", closed="left").agg(
pl.col("time").cumcount().reverse().head(3).alias("day/eom"),
((pl.col("time") - pl.col("time").first()).last().dt.days() + 1).alias(
((pl.col("time") - pl.col("time").first()).last().dt.total_days() + 1).alias(
"days_in_month"
),
)
Expand Down
14 changes: 7 additions & 7 deletions py-polars/docs/source/reference/expressions/temporal.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,30 +16,30 @@ The following methods are available under the `expr.dt` attribute.
Expr.dt.date
Expr.dt.datetime
Expr.dt.day
Expr.dt.days
Expr.dt.total_days
Expr.dt.dst_offset
Expr.dt.epoch
Expr.dt.hour
Expr.dt.hours
Expr.dt.total_hours
Expr.dt.is_leap_year
Expr.dt.iso_year
Expr.dt.microsecond
Expr.dt.microseconds
Expr.dt.total_microseconds
Expr.dt.millisecond
Expr.dt.milliseconds
Expr.dt.total_milliseconds
Expr.dt.minute
Expr.dt.minutes
Expr.dt.total_minutes
Expr.dt.month
Expr.dt.month_start
Expr.dt.month_end
Expr.dt.nanosecond
Expr.dt.nanoseconds
Expr.dt.total_nanoseconds
Expr.dt.offset_by
Expr.dt.ordinal_day
Expr.dt.quarter
Expr.dt.round
Expr.dt.second
Expr.dt.seconds
Expr.dt.total_seconds
Expr.dt.strftime
Expr.dt.time
Expr.dt.timestamp
Expand Down
14 changes: 7 additions & 7 deletions py-polars/docs/source/reference/series/temporal.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,34 +16,34 @@ The following methods are available under the `Series.dt` attribute.
Series.dt.date
Series.dt.datetime
Series.dt.day
Series.dt.days
Series.dt.total_days
Series.dt.dst_offset
Series.dt.epoch
Series.dt.hour
Series.dt.hours
Series.dt.total_hours
Series.dt.is_leap_year
Series.dt.iso_year
Series.dt.max
Series.dt.mean
Series.dt.median
Series.dt.microsecond
Series.dt.microseconds
Series.dt.total_microseconds
Series.dt.millisecond
Series.dt.milliseconds
Series.dt.total_milliseconds
Series.dt.min
Series.dt.minute
Series.dt.minutes
Series.dt.total_minutes
Series.dt.month
Series.dt.month_start
Series.dt.month_end
Series.dt.nanosecond
Series.dt.nanoseconds
Series.dt.total_nanoseconds
Series.dt.offset_by
Series.dt.ordinal_day
Series.dt.quarter
Series.dt.round
Series.dt.second
Series.dt.seconds
Series.dt.total_seconds
Series.dt.strftime
Series.dt.time
Series.dt.timestamp
Expand Down
126 changes: 99 additions & 27 deletions py-polars/polars/expr/datetime.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,10 @@
from polars.utils._parse_expr_input import parse_as_expression
from polars.utils._wrap import wrap_expr
from polars.utils.convert import _timedelta_to_pl_duration
from polars.utils.deprecation import rename_use_earliest_to_ambiguous
from polars.utils.deprecation import (
deprecate_renamed_function,
rename_use_earliest_to_ambiguous,
)

if TYPE_CHECKING:
from datetime import timedelta
Expand Down Expand Up @@ -1454,9 +1457,20 @@ def replace_time_zone(
self._pyexpr.dt_replace_time_zone(time_zone, ambiguous._pyexpr)
)

@deprecate_renamed_function("total_days", version="0.19.3")
def days(self) -> Expr:
"""
Extract the days from a Duration type.
Extract the total days from a Duration type.
.. deprecated:: 0.19.3
Use :meth:`total_days` instead.
"""
return self.total_days()

def total_days(self) -> Expr:
"""
Extract the total days from a Duration type.
Returns
-------
Expand All @@ -1476,7 +1490,7 @@ def days(self) -> Expr:
>>> df.select(
... [
... pl.col("date"),
... pl.col("date").diff().dt.days().alias("days_diff"),
... pl.col("date").diff().dt.total_days().alias("days_diff"),
... ]
... )
shape: (3, 2)
Expand All @@ -1493,9 +1507,20 @@ def days(self) -> Expr:
"""
return wrap_expr(self._pyexpr.duration_days())

@deprecate_renamed_function("total_hours", version="0.19.3")
def hours(self) -> Expr:
"""
Extract the hours from a Duration type.
Extract the total hours from a Duration type.
.. deprecated:: 0.19.3
Use :meth:`total_hours` instead.
"""
return self.total_hours()

def total_hours(self) -> Expr:
"""
Extract the total hours from a Duration type.
Returns
-------
Expand All @@ -1515,7 +1540,7 @@ def hours(self) -> Expr:
>>> df.select(
... [
... pl.col("date"),
... pl.col("date").diff().dt.hours().alias("hours_diff"),
... pl.col("date").diff().dt.total_hours().alias("hours_diff"),
... ]
... )
shape: (4, 2)
Expand All @@ -1533,9 +1558,20 @@ def hours(self) -> Expr:
"""
return wrap_expr(self._pyexpr.duration_hours())

@deprecate_renamed_function("total_minutes", version="0.19.3")
def minutes(self) -> Expr:
"""
Extract the minutes from a Duration type.
Extract the total minutes from a Duration type.
.. deprecated:: 0.19.3
Use :meth:`total_minutes` instead.
"""
return self.total_minutes()

def total_minutes(self) -> Expr:
"""
Extract the total minutes from a Duration type.
Returns
-------
Expand All @@ -1555,7 +1591,7 @@ def minutes(self) -> Expr:
>>> df.select(
... [
... pl.col("date"),
... pl.col("date").diff().dt.minutes().alias("minutes_diff"),
... pl.col("date").diff().dt.total_minutes().alias("minutes_diff"),
... ]
... )
shape: (4, 2)
Expand All @@ -1573,9 +1609,20 @@ def minutes(self) -> Expr:
"""
return wrap_expr(self._pyexpr.duration_minutes())

@deprecate_renamed_function("total_seconds", version="0.19.3")
def seconds(self) -> Expr:
"""
Extract the seconds from a Duration type.
Extract the total seconds from a Duration type.
.. deprecated:: 0.19.3
Use :meth:`total_seconds` instead.
"""
return self.total_seconds()

def total_seconds(self) -> Expr:
"""
Extract the total seconds from a Duration type.
Returns
-------
Expand All @@ -1596,10 +1643,8 @@ def seconds(self) -> Expr:
... }
... )
>>> df.select(
... [
... pl.col("date"),
... pl.col("date").diff().dt.seconds().alias("seconds_diff"),
... ]
... pl.col("date"),
... pl.col("date").diff().dt.total_seconds().alias("seconds_diff"),
... )
shape: (5, 2)
┌─────────────────────┬──────────────┐
Expand All @@ -1617,9 +1662,20 @@ def seconds(self) -> Expr:
"""
return wrap_expr(self._pyexpr.duration_seconds())

@deprecate_renamed_function("total_milliseconds", version="0.19.3")
def milliseconds(self) -> Expr:
"""
Extract the milliseconds from a Duration type.
Extract the total milliseconds from a Duration type.
.. deprecated:: 0.19.3
Use :meth:`total_milliseconds` instead.
"""
return self.total_milliseconds()

def total_milliseconds(self) -> Expr:
"""
Extract the total milliseconds from a Duration type.
Returns
-------
Expand All @@ -1640,10 +1696,8 @@ def milliseconds(self) -> Expr:
... }
... )
>>> df.select(
... [
... pl.col("date"),
... pl.col("date").diff().dt.milliseconds().alias("milliseconds_diff"),
... ]
... pl.col("date"),
... milliseconds_diff=pl.col("date").diff().dt.total_milliseconds(),
... )
shape: (1_001, 2)
┌─────────────────────────┬───────────────────┐
Expand All @@ -1665,9 +1719,20 @@ def milliseconds(self) -> Expr:
"""
return wrap_expr(self._pyexpr.duration_milliseconds())

@deprecate_renamed_function("total_microseconds", version="0.19.3")
def microseconds(self) -> Expr:
"""
Extract the microseconds from a Duration type.
Extract the total microseconds from a Duration type.
.. deprecated:: 0.19.3
Use :meth:`total_microseconds` instead.
"""
return self.total_microseconds()

def total_microseconds(self) -> Expr:
"""
Extract the total microseconds from a Duration type.
Returns
-------
Expand All @@ -1688,10 +1753,8 @@ def microseconds(self) -> Expr:
... }
... )
>>> df.select(
... [
... pl.col("date"),
... pl.col("date").diff().dt.microseconds().alias("microseconds_diff"),
... ]
... pl.col("date"),
... microseconds_diff=pl.col("date").diff().dt.total_microseconds(),
... )
shape: (1_001, 2)
┌─────────────────────────┬───────────────────┐
Expand All @@ -1713,9 +1776,20 @@ def microseconds(self) -> Expr:
"""
return wrap_expr(self._pyexpr.duration_microseconds())

@deprecate_renamed_function("total_nanoseconds", version="0.19.3")
def nanoseconds(self) -> Expr:
"""
Extract the nanoseconds from a Duration type.
Extract the total nanoseconds from a Duration type.
.. deprecated:: 0.19.3
Use :meth:`total_nanoseconds` instead.
"""
return self.total_nanoseconds()

def total_nanoseconds(self) -> Expr:
"""
Extract the total nanoseconds from a Duration type.
Returns
-------
Expand All @@ -1736,10 +1810,8 @@ def nanoseconds(self) -> Expr:
... }
... )
>>> df.select(
... [
... pl.col("date"),
... pl.col("date").diff().dt.nanoseconds().alias("nanoseconds_diff"),
... ]
... pl.col("date"),
... nanoseconds_diff=pl.col("date").diff().dt.total_nanoseconds(),
... )
shape: (1_001, 2)
┌─────────────────────────┬──────────────────┐
Expand Down
Loading

0 comments on commit 6d6a997

Please sign in to comment.