polars-df 0.23.0 → 0.24.0

data/lib/polars/date_time_name_space.rb

@@ -104,49 +104,6 @@ module Polars
       Utils.wrap_s(_s).max
     end
 
-    # Return median as Ruby object.
-    #
-    # @return [Object]
-    #
-    # @example
-    #   date = Polars.datetime_range(
-    #     DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 3), "1d", eager: true
-    #   ).alias("datetime")
-    #   # =>
-    #   # shape: (3,)
-    #   # Series: 'datetime' [datetime[ns]]
-    #   # [
-    #   #         2001-01-01 00:00:00
-    #   #         2001-01-02 00:00:00
-    #   #         2001-01-03 00:00:00
-    #   # ]
-    #
-    # @example
-    #   date.dt.median
-    #   # => 2001-01-02 00:00:00 UTC
-    def median
-      _s.median
-    end
-
-    # Return mean as Ruby object.
-    #
-    # @return [Object]
-    #
-    # @example
-    #   s = Polars::Series.new([Date.new(2001, 1, 1), Date.new(2001, 1, 2)])
-    #   s.dt.mean
-    #   # => 2001-01-01 12:00:00 UTC
-    #
-    # @example
-    #   s = Polars::Series.new(
-    #     [DateTime.new(2001, 1, 1), DateTime.new(2001, 1, 2), DateTime.new(2001, 1, 3)]
-    #   )
-    #   s.dt.mean
-    #   # => 2001-01-02 00:00:00 UTC
-    def mean
-      _s.mean
-    end
-
     # Convert a Date/Time/Datetime column into a String column with the given format.
     #
     # Similar to `cast(Polars::String)`, but this method allows you to customize the
@@ -173,13 +130,18 @@ module Polars
     #   #         "2020/04/01"
     #   #         "2020/05/01"
     #   # ]
-    def to_string(format)
+    def to_string(format = nil)
       super
     end
 
-    # Format Date/datetime with a formatting rule.
+    # Convert a Date/Time/Datetime column into a String column with the given format.
     #
-    # See [chrono strftime/strptime](https://docs.rs/chrono/0.4.19/chrono/format/strftime/index.html).
+    # Similar to `cast(Polars::String)`, but this method allows you to customize the
+    # formatting of the resulting string.
+    #
+    # @param format [String]
+    #   Format to use, refer to the [chrono strftime documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)
+    #   for specification. Example: `"%y-%m-%d"`.
     #
     # @return [Series]
     #
@@ -197,7 +159,7 @@ module Polars
     #   #         "2020/04/01"
     #   #         "2020/05/01"
     #   # ]
-    def strftime(fmt)
+    def strftime(format)
       super
     end
 
@@ -300,7 +262,7 @@ module Polars
     # @param week_mask [Array]
     #   Which days of the week to count. The default is Monday to Friday.
     #   If you wanted to count only Monday to Thursday, you would pass
-    #   `(True, True, True, True, False, False, False)`.
+    #   `[true, true, true, true, false, false, false]`.
     #
     # @return [Series]
     #
@@ -429,6 +391,32 @@ module Polars
       super
     end
 
+    # Extract the number of days in the month from the underlying date representation.
+    #
+    # Applies to Date and Datetime columns.
+    #
+    # Returns the number of days in the month.
+    # The return value ranges from 28 to 31.
+    #
+    # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new(
+    #     "date", [Date.new(2001, 1, 1), Date.new(2001, 2, 1), Date.new(2000, 2, 1)]
+    #   )
+    #   s.dt.days_in_month
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'date' [i8]
+    #   # [
+    #   #         31
+    #   #         28
+    #   #         29
+    #   # ]
+    def days_in_month
+      super
+    end
+
     # Extract the week from the underlying date representation.
     #
     # Applies to Date and Datetime columns.
@@ -859,43 +847,6 @@ module Polars
       super
     end
 
-    # Set time unit a Series of dtype Datetime or Duration.
-    #
-    # This does not modify underlying data, and should be used to fix an incorrect
-    # time unit.
-    #
-    # @param time_unit ["ns", "us", "ms"]
-    #   Time unit for the `Datetime` Series.
-    #
-    # @return [Series]
-    #
-    # @example
-    #   start = DateTime.new(2001, 1, 1)
-    #   stop = DateTime.new(2001, 1, 3)
-    #   date = Polars.datetime_range(start, stop, "1d", time_unit: "ns", eager: true).alias("datetime")
-    #   # =>
-    #   # shape: (3,)
-    #   # Series: 'datetime' [datetime[ns]]
-    #   # [
-    #   #         2001-01-01 00:00:00
-    #   #         2001-01-02 00:00:00
-    #   #         2001-01-03 00:00:00
-    #   # ]
-    #
-    # @example
-    #   date.dt.with_time_unit("us").alias("tu_us")
-    #   # =>
-    #   # shape: (3,)
-    #   # Series: 'tu_us' [datetime[μs]]
-    #   # [
-    #   #         +32971-04-28 00:00:00
-    #   #         +32974-01-22 00:00:00
-    #   #         +32976-10-18 00:00:00
-    #   # ]
-    def with_time_unit(time_unit)
-      super
-    end
-
     # Cast the underlying data to another time unit. This may lose precision.
     #
     # @param time_unit ["ns", "us", "ms"]
@@ -1060,21 +1011,11 @@ module Polars
       super
     end
 
-    # Localize tz-naive Datetime Series to tz-aware Datetime Series.
-    #
-    # This method takes a naive Datetime Series and makes this time zone aware.
-    # It does not move the time to another time zone.
-    #
-    # @param tz [String]
-    #   Time zone for the `Datetime` Series.
-    #
-    # @return [Series]
-    def tz_localize(tz)
-      super
-    end
-
     # Extract the days from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the day.
+    #
     # @return [Series]
     #
     # @example
@@ -1090,13 +1031,15 @@ module Polars
     #   #         31
     #   #         30
     #   # ]
-    def total_days
+    def total_days(fractional: false)
       super
     end
-    alias_method :days, :total_days
 
     # Extract the hours from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the hour.
+    #
     # @return [Series]
     #
     # @example
@@ -1122,13 +1065,15 @@ module Polars
     #   #         24
     #   #         24
     #   # ]
-    def total_hours
+    def total_hours(fractional: false)
       super
     end
-    alias_method :hours, :total_hours
 
     # Extract the minutes from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the minute.
+    #
     # @return [Series]
     #
     # @example
@@ -1154,13 +1099,15 @@ module Polars
     #   #         1440
     #   #         1440
     #   # ]
-    def total_minutes
+    def total_minutes(fractional: false)
       super
     end
-    alias_method :minutes, :total_minutes
 
     # Extract the seconds from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the second.
+    #
     # @return [Series]
     #
     # @example
@@ -1190,13 +1137,15 @@ module Polars
     #   #         60
     #   #         60
     #   # ]
-    def total_seconds
+    def total_seconds(fractional: false)
       super
     end
-    alias_method :seconds, :total_seconds
 
     # Extract the milliseconds from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the millisecond.
+    #
     # @return [Series]
     #
     # @example
@@ -1222,13 +1171,15 @@ module Polars
     #   #         1
     #   #         1
     #   # ]
-    def total_milliseconds
+    def total_milliseconds(fractional: false)
       super
     end
-    alias_method :milliseconds, :total_milliseconds
 
     # Extract the microseconds from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include the fractional component of the microsecond.
+    #
     # @return [Series]
     #
     # @example
@@ -1254,13 +1205,17 @@ module Polars
     #   #         1000
     #   #         1000
     #   # ]
-    def total_microseconds
+    def total_microseconds(fractional: false)
       super
     end
-    alias_method :microseconds, :total_microseconds
 
     # Extract the nanoseconds from a Duration type.
     #
+    # @param fractional [Boolean]
+    #   Whether to include return the result as a `Float64`.
+    #   Because the smallest `TimeUnit` is `'ns'`, the
+    #   fractional component will always be zero.
+    #
     # @return [Series]
     #
     # @example
@@ -1286,10 +1241,9 @@ module Polars
     #   #         1000000
     #   #         1000000
     #   # ]
-    def total_nanoseconds
+    def total_nanoseconds(fractional: false)
       super
     end
-    alias_method :nanoseconds, :total_nanoseconds
 
     # Offset this date by a relative time offset.
     #
@@ -1522,6 +1476,20 @@ module Polars
     #   Unit of time.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new(
+    #     "dtm",
+    #     [DateTime.new(2022, 12, 31, 10, 30, 45), DateTime.new(2023, 7, 5, 23, 59, 59)]
+    #   )
+    #   s.dt.combine(Time.new(2000, 1, 1, 1, 2, 3.456))
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'dtm' [datetime[μs]]
+    #   # [
+    #   #         2022-12-31 01:02:03.456
+    #   #         2023-07-05 01:02:03.456
+    #   # ]
     def combine(time, time_unit: "us")
       super
     end

data/lib/polars/dynamic_group_by.rb

@@ -10,10 +10,10 @@ module Polars
       every,
       period,
       offset,
-      truncate,
       include_boundaries,
       closed,
-      by,
+      label,
+      group_by,
       start_by
     )
       period = Utils.parse_as_duration_string(period)
@@ -25,10 +25,10 @@ module Polars
       @every = every
       @period = period
       @offset = offset
-      @truncate = truncate
       @include_boundaries = include_boundaries
       @closed = closed
-      @by = by
+      @label = label
+      @group_by = group_by
       @start_by = start_by
     end
 
@@ -39,14 +39,14 @@ module Polars
           every: @every,
           period: @period,
           offset: @offset,
-          truncate: @truncate,
           include_boundaries: @include_boundaries,
           closed: @closed,
-          by: @by,
+          label: @label,
+          group_by: @group_by,
           start_by: @start_by
         )
         .agg(*aggs, **named_aggs)
-        .collect(no_optimization: true, string_cache: false)
+        .collect(optimizations: QueryOptFlags.none)
     end
   end
 end

data/lib/polars/exceptions.rb

@@ -3,13 +3,61 @@ module Polars
   # Base class for all Polars errors.
   class Error < StandardError; end
 
+  # @private
+  # Exception raised when a specified column is not found.
+  class ColumnNotFoundError < Error; end
+
+  # @private
+  # Exception raised when Polars could not perform an underlying computation.
+  class ComputeError < Error; end
+
+  # @private
+  # Exception raised when a column name is duplicated.
+  class DuplicateError < Error; end
+
   # @private
   # Exception raised when an operation is not allowed (or possible) against a given object or data structure.
   class InvalidOperationError < Error; end
 
   # @private
-  # Exception raised when an unsupported testing assert is made.
-  class InvalidAssert < Error; end
+  # Exception raised when an operation cannot be performed on an empty data structure.
+  class NoDataError < Error; end
+
+  # @private
+  # Exception raised when the given index is out of bounds.
+  class OutOfBoundsError < Error; end
+
+  # @private
+  # Exception raised when an unexpected state causes a panic in the underlying Rust library.
+  class PanicException < Error; end
+
+  # @private
+  # Exception raised when an unexpected schema mismatch causes an error.
+  class SchemaError < Error; end
+
+  # @private
+  # Exception raised when a specified schema field is not found.
+  class SchemaFieldNotFoundError < Error; end
+
+  # @private
+  # Exception raised when trying to perform operations on data structures with incompatible shapes.
+  class ShapeError < Error; end
+
+  # @private
+  # Exception raised when an error occurs in the SQL interface.
+  class SQLInterfaceError < Error; end
+
+  # @private
+  # Exception raised from the SQL interface when encountering invalid syntax.
+  class SQLSyntaxError < Error; end
+
+  # @private
+  # Exception raised when string caches come from different sources.
+  class StringCacheMismatchError < Error; end
+
+  # @private
+  # Exception raised when a specified Struct field is not found.
+  class StructFieldNotFoundError < Error; end
 
   # @private
   # Exception raised when the number of returned rows does not match expectation.
@@ -23,14 +71,6 @@ module Polars
   # Exception raised when more rows than expected are returned.
   class TooManyRowsReturned < RowsException; end
 
-  # @private
-  # Exception raised when Polars could not perform an underlying computation.
-  class ComputeError < Error; end
-
-  # @private
-  # Exception raised when a column name is duplicated.
-  class DuplicateError < Error; end
-
   # @private
   class AssertionError < Error; end