polars-df 0.23.0 → 0.24.0

data/lib/polars/functions/lit.rb

@@ -3,7 +3,23 @@ module Polars
     # Return an expression representing a literal value.
     #
     # @return [Expr]
-    def lit(value, dtype: nil, allow_object: nil)
+    #
+    # @example Literal scalar values:
+    #   Polars.lit(1)
+    #   Polars.lit(5.5)
+    #   Polars.lit(nil)
+    #   Polars.lit("foo_bar")
+    #   Polars.lit(Date.new(2021, 1, 20))
+    #   Polars.lit(DateTime.new(2023, 3, 31, 10, 30, 45))
+    #
+    # @example Literal list/Series data (1D):
+    #   Polars.lit([1, 2, 3])
+    #   Polars.lit(Polars::Series.new("x", [1, 2, 3]))
+    #
+    # @example Literal list/Series data (2D):
+    #   Polars.lit([[1, 2], [3, 4]])
+    #   Polars.lit(Polars::Series.new("y", [[1, 2], [3, 4]]))
+    def lit(value, dtype: nil, allow_object: false)
       if value.is_a?(::Time) || value.is_a?(::DateTime)
         time_unit = dtype&.time_unit || "ns"
         time_zone = dtype.&time_zone

data/lib/polars/functions/range/int_range.rb

@@ -12,7 +12,7 @@ module Polars
     # @param step [Integer]
     #   Step size of the range.
     # @param eager [Boolean]
-    #   If eager evaluation is `True`, a Series is returned instead of an Expr.
+    #   If eager evaluation is `true`, a Series is returned instead of an Expr.
     # @param dtype [Symbol]
     #   Apply an explicit integer dtype to the resulting expression (default is `Int64`).
     #
@@ -28,7 +28,7 @@ module Polars
     #   #         1
     #   #         2
     #   # ]
-    def int_range(start, stop = nil, step: 1, eager: false, dtype: nil)
+    def int_range(start = 0, stop = nil, step: 1, eager: false, dtype: Int64)
       if stop.nil?
         stop = start
         start = 0
@@ -47,5 +47,77 @@ module Polars
       result
     end
     alias_method :arange, :int_range
+
+    # Generate a range of integers for each row of the input columns.
+    #
+    # @param start [Integer, Expr, Series]
+    #   Start of the range (inclusive). Defaults to 0.
+    # @param stop [Integer, Expr, Series]
+    #   End of the range (exclusive). If set to `nil` (default),
+    #   the value of `start` is used and `start` is set to `0`.
+    # @param step [Integer]
+    #   Step size of the range.
+    # @param dtype [Object]
+    #   Integer data type of the ranges. Defaults to `Int64`.
+    # @param eager [Boolean]
+    #   Evaluate immediately and return a `Series`.
+    #   If set to `false` (default), return an expression instead.
+    #
+    # @return [Expr, Series]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"start" => [1, -1], "end" => [3, 2]})
+    #   df.with_columns(int_range: Polars.int_ranges("start", "end"))
+    #   # =>
+    #   # shape: (2, 3)
+    #   # ┌───────┬─────┬────────────┐
+    #   # │ start ┆ end ┆ int_range  │
+    #   # │ ---   ┆ --- ┆ ---        │
+    #   # │ i64   ┆ i64 ┆ list[i64]  │
+    #   # ╞═══════╪═════╪════════════╡
+    #   # │ 1     ┆ 3   ┆ [1, 2]     │
+    #   # │ -1    ┆ 2   ┆ [-1, 0, 1] │
+    #   # └───────┴─────┴────────────┘
+    #
+    # @example `end` can be omitted for a shorter syntax.
+    #   df.select("end", int_range: Polars.int_ranges("end"))
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬───────────┐
+    #   # │ end ┆ int_range │
+    #   # │ --- ┆ ---       │
+    #   # │ i64 ┆ list[i64] │
+    #   # ╞═════╪═══════════╡
+    #   # │ 3   ┆ [0, 1, 2] │
+    #   # │ 2   ┆ [0, 1]    │
+    #   # └─────┴───────────┘
+    def int_ranges(
+      start = 0,
+      stop = nil,
+      step: 1,
+      dtype: Int64,
+      eager: false
+    )
+      if stop.nil?
+        stop = start
+        start = 0
+      end
+
+      dtype_expr = Utils.parse_into_datatype_expr(dtype)
+      start_rbexpr = Utils.parse_into_expression(start)
+      end_rbexpr = Utils.parse_into_expression(stop)
+      step_rbexpr = Utils.parse_into_expression(step)
+      result = Utils.wrap_expr(
+        Plr.int_ranges(
+          start_rbexpr, end_rbexpr, step_rbexpr, dtype_expr._rbdatatype_expr
+        )
+      )
+
+      if eager
+        return F.select(result).to_series
+      end
+
+      result
+    end
   end
 end

data/lib/polars/functions/range/linear_space.rb

@@ -0,0 +1,77 @@
+module Polars
+  module Functions
+    # Generate a sequence of evenly-spaced values for each row between `start` and `end`.
+    #
+    # The number of values in each sequence is determined by `num_samples`.
+    #
+    # @param start [Object]
+    #   Lower bound of the range.
+    # @param stop [Object]
+    #   Upper bound of the range.
+    # @param num_samples [Integer]
+    #   Number of samples in the output sequence.
+    # @param closed ['both', 'left', 'right', 'none']
+    #   Define which sides of the interval are closed (inclusive).
+    # @param as_array [Boolean]
+    #   Return result as a fixed-length `Array`. `num_samples` must be a constant.
+    # @param eager [Boolean]
+    #   Evaluate immediately and return a `Series`.
+    #   If set to `false` (default), return an expression instead.
+    #
+    # @return [Expr, Series]
+    #
+    # @note
+    #   This functionality is experimental. It may be changed at any point without it
+    #   being considered a breaking change.
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"start" => [1, -1], "end" => [3, 2], "num_samples" => [4, 5]})
+    #   df.with_columns(ls: Polars.linear_spaces("start", "end", "num_samples"))
+    #   # =>
+    #   # shape: (2, 4)
+    #   # ┌───────┬─────┬─────────────┬────────────────────────┐
+    #   # │ start ┆ end ┆ num_samples ┆ ls                     │
+    #   # │ ---   ┆ --- ┆ ---         ┆ ---                    │
+    #   # │ i64   ┆ i64 ┆ i64         ┆ list[f64]              │
+    #   # ╞═══════╪═════╪═════════════╪════════════════════════╡
+    #   # │ 1     ┆ 3   ┆ 4           ┆ [1.0, 1.666667, … 3.0] │
+    #   # │ -1    ┆ 2   ┆ 5           ┆ [-1.0, -0.25, … 2.0]   │
+    #   # └───────┴─────┴─────────────┴────────────────────────┘
+    #
+    # @example
+    #   df.with_columns(ls: Polars.linear_spaces("start", "end", 3, as_array: true))
+    #   # =>
+    #   # shape: (2, 4)
+    #   # ┌───────┬─────┬─────────────┬──────────────────┐
+    #   # │ start ┆ end ┆ num_samples ┆ ls               │
+    #   # │ ---   ┆ --- ┆ ---         ┆ ---              │
+    #   # │ i64   ┆ i64 ┆ i64         ┆ array[f64, 3]    │
+    #   # ╞═══════╪═════╪═════════════╪══════════════════╡
+    #   # │ 1     ┆ 3   ┆ 4           ┆ [1.0, 2.0, 3.0]  │
+    #   # │ -1    ┆ 2   ┆ 5           ┆ [-1.0, 0.5, 2.0] │
+    #   # └───────┴─────┴─────────────┴──────────────────┘
+    def linear_spaces(
+      start,
+      stop,
+      num_samples,
+      closed: "both",
+      as_array: false,
+      eager: false
+    )
+      start_rbexpr = Utils.parse_into_expression(start)
+      end_rbexpr = Utils.parse_into_expression(stop)
+      num_samples_rbexpr = Utils.parse_into_expression(num_samples)
+      result = Utils.wrap_expr(
+        Plr.linear_spaces(
+          start_rbexpr, end_rbexpr, num_samples_rbexpr, closed, as_array
+        )
+      )
+
+      if eager
+        return F.select(result).to_series
+      end
+
+      result
+    end
+  end
+end

data/lib/polars/functions/range/time_range.rb

@@ -12,7 +12,7 @@ module Polars
     #   Define which sides of the range are closed (inclusive).
     # @param eager [Boolean]
     #   Evaluate immediately and return a `Series`.
-    #   If set to `False` (default), return an expression instead.
+    #   If set to `false` (default), return an expression instead.
     #
     # @return [Object]
     #

data/lib/polars/functions/repeat.rb

@@ -12,8 +12,6 @@ module Polars
     #   Int64 is required to fit the given value. Defaults to Float64 for float values.
     # @param eager [Boolean]
     #   Run eagerly and collect into a `Series`.
-    # @param name [String]
-    #   Only used in `eager` mode. As expression, use `alias`.
     #
     # @return [Object]
     #
@@ -38,20 +36,13 @@ module Polars
     #   #         3
     #   #         3
     #   # ]
-    def repeat(value, n, dtype: nil, eager: false, name: nil)
-      if !name.nil?
-        warn "the `name` argument is deprecated. Use the `alias` method instead."
-      end
-
+    def repeat(value, n, dtype: nil, eager: false)
       if n.is_a?(Integer)
         n = lit(n)
       end
 
       value = Utils.parse_into_expression(value, str_as_lit: true)
       expr = Utils.wrap_expr(Plr.repeat(value, n._rbexpr, dtype))
-      if !name.nil?
-        expr = expr.alias(name)
-      end
       if eager
         return select(expr).to_series
       end
@@ -82,7 +73,7 @@ module Polars
     #   #         1
     #   #         1
     #   # ]
-    def ones(n, dtype: nil, eager: true)
+    def ones(n, dtype: Float64, eager: false)
       if (zero = _one_or_zero_by_dtype(1, dtype)).nil?
         msg = "invalid dtype for `ones`; found #{dtype}"
         raise TypeError, msg
@@ -115,7 +106,7 @@ module Polars
     #   #         0
     #   #         0
     #   # ]
-    def zeros(n, dtype: nil, eager: true)
+    def zeros(n, dtype: Float64, eager: false)
       if (zero = _one_or_zero_by_dtype(0, dtype)).nil?
         msg = "invalid dtype for `zeros`; found #{dtype}"
         raise TypeError, msg

data/lib/polars/functions/whenthen.rb

@@ -6,7 +6,7 @@ module Polars
     #
     # @example Below we add a column with the value 1, where column "foo" > 2 and the value -1 where it isn't.
     #   df = Polars::DataFrame.new({"foo" => [1, 3, 4], "bar" => [3, 4, 0]})
-    #   df.with_column(Polars.when(Polars.col("foo") > 2).then(Polars.lit(1)).otherwise(Polars.lit(-1)))
+    #   df.with_columns(Polars.when(Polars.col("foo") > 2).then(Polars.lit(1)).otherwise(Polars.lit(-1)))
     #   # =>
     #   # shape: (3, 3)
     #   # ┌─────┬─────┬─────────┐
@@ -40,7 +40,7 @@ module Polars
     #   # │ 4   ┆ 0   ┆ 1   │
     #   # └─────┴─────┴─────┘
     #
-    # @example The `otherwise` at the end is optional. If left out, any rows where none of the `when` expressions evaluate to True, are set to `null`:
+    # @example The `otherwise` at the end is optional. If left out, any rows where none of the `when` expressions evaluate to true, are set to `null`:
     #   df.with_columns(Polars.when(Polars.col("foo") > 2).then(1).alias("val"))
     #   # =>
     #   # shape: (3, 3)

data/lib/polars/group_by.rb

@@ -2,9 +2,10 @@ module Polars
   # Starts a new GroupBy operation.
   class GroupBy
     # @private
-    def initialize(df, by, maintain_order: false)
+    def initialize(df, by, maintain_order:, **named_by)
       @df = df
       @by = by
+      @named_by = named_by
       @maintain_order = maintain_order
     end
 
@@ -39,9 +40,9 @@ module Polars
       groups_df =
         @df.lazy
           .with_row_index(name: temp_col)
-          .group_by(@by, maintain_order: @maintain_order)
+          .group_by(@by, **@named_by, maintain_order: @maintain_order)
           .agg(Polars.col(temp_col))
-          .collect(no_optimization: true)
+          .collect(optimizations: QueryOptFlags.none)
 
       group_names = groups_df.select(Polars.all.exclude(temp_col))
 
@@ -202,9 +203,9 @@ module Polars
     #   # └─────┴───────┴────────────────┘
     def agg(*aggs, **named_aggs)
       @df.lazy
-        .group_by(@by, maintain_order: @maintain_order)
+        .group_by(@by, **@named_by, maintain_order: @maintain_order)
         .agg(*aggs, **named_aggs)
-        .collect(no_optimization: true)
+        .collect(optimizations: QueryOptFlags.none)
     end
 
     # Get the first `n` rows of each group.
@@ -253,9 +254,9 @@ module Polars
     #   # └─────────┴─────┘
     def head(n = 5)
       @df.lazy
-        .group_by(@by, maintain_order: @maintain_order)
+        .group_by(@by, **@named_by, maintain_order: @maintain_order)
         .head(n)
-        .collect(no_optimization: true)
+        .collect(optimizations: QueryOptFlags._eager)
     end
 
     # Get the last `n` rows of each group.
@@ -304,9 +305,71 @@ module Polars
     #   # └─────────┴─────┘
     def tail(n = 5)
       @df.lazy
-        .group_by(@by, maintain_order: @maintain_order)
+        .group_by(@by, **@named_by, maintain_order: @maintain_order)
         .tail(n)
-        .collect(no_optimization: true)
+        .collect(optimizations: QueryOptFlags.none)
+    end
+
+    # Aggregate the groups into Series.
+    #
+    # @return [DataFrame]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => ["one", "two", "one", "two"], "b" => [1, 2, 3, 4]})
+    #   df.group_by("a", maintain_order: true).all
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌─────┬───────────┐
+    #   # │ a   ┆ b         │
+    #   # │ --- ┆ ---       │
+    #   # │ str ┆ list[i64] │
+    #   # ╞═════╪═══════════╡
+    #   # │ one ┆ [1, 3]    │
+    #   # │ two ┆ [2, 4]    │
+    #   # └─────┴───────────┘
+    def all
+      agg(F.all)
+    end
+
+    # Return the number of rows in each group.
+    #
+    # @param name [String]
+    #   Assign a name to the resulting column; if unset, defaults to "len".
+    #
+    # @return [DataFrame]
+    #
+    # @example
+    #   df = Polars::DataFrame.new({"a" => ["Apple", "Apple", "Orange"], "b" => [1, nil, 2]})
+    #   df.group_by("a").len
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌────────┬─────┐
+    #   # │ a      ┆ len │
+    #   # │ ---    ┆ --- │
+    #   # │ str    ┆ u32 │
+    #   # ╞════════╪═════╡
+    #   # │ Apple  ┆ 2   │
+    #   # │ Orange ┆ 1   │
+    #   # └────────┴─────┘
+    #
+    # @example
+    #   df.group_by("a").len(name: "n")
+    #   # =>
+    #   # shape: (2, 2)
+    #   # ┌────────┬─────┐
+    #   # │ a      ┆ n   │
+    #   # │ ---    ┆ --- │
+    #   # │ str    ┆ u32 │
+    #   # ╞════════╪═════╡
+    #   # │ Apple  ┆ 2   │
+    #   # │ Orange ┆ 1   │
+    #   # └────────┴─────┘
+    def len(name: nil)
+      len_expr = F.len
+      if !name.nil?
+        len_expr = len_expr.alias(name)
+      end
+      agg(len_expr)
     end
 
     # Aggregate the first values in the group.
@@ -598,16 +661,5 @@ module Polars
     def median
       agg(Polars.all.median)
     end
-
-    # Plot data.
-    #
-    # @return [Vega::LiteChart]
-    def plot(*args, **options)
-      raise ArgumentError, "Multiple groups not supported" if @by.is_a?(::Array) && @by.size > 1
-      # same message as Ruby
-      raise ArgumentError, "unknown keyword: :group" if options.key?(:group)
-
-      @df.plot(*args, **options, group: @by)
-    end
   end
 end

data/lib/polars/iceberg_dataset.rb

@@ -12,11 +12,6 @@ module Polars
     end
 
     def to_lazyframe
-      # for iceberg < 0.1.3
-      if !@source.respond_to?(:scan)
-        return @source.to_polars(snapshot_id: @snapshot_id, storage_options: @storage_options)
-      end
-
       scan = @source.scan(snapshot_id: @snapshot_id)
       files = scan.plan_files
 
@@ -66,7 +61,7 @@ module Polars
         scan_options = {
           storage_options: @storage_options,
           cast_options: Polars::ScanCastOptions._default_iceberg,
-          allow_missing_columns: true,
+          missing_columns: "insert",
           extra_columns: "ignore",
           _column_mapping: column_mapping,
           _deletion_files: deletion_files

data/lib/polars/in_process_query.rb

@@ -0,0 +1,37 @@
+module Polars
+  # A placeholder for an in process query.
+  #
+  # This can be used to do something else while a query is running.
+  # The queries can be cancelled. You can peek if the query is finished,
+  # or you can await the result.
+  class InProcessQuery
+    # @private
+    attr_accessor :_inner
+
+    def initialize(ipq)
+      self._inner = ipq
+    end
+
+    # Cancel the query at earliest convenience.
+    def cancel
+      _inner.cancel
+    end
+
+    # Fetch the result.
+    #
+    # If it is ready, a materialized DataFrame is returned.
+    # If it is not ready it will return `nil`.
+    def fetch
+      if !(out = _inner.fetch).nil?
+        Utils.wrap_df(out)
+      else
+        nil
+      end
+    end
+
+    # Await the result synchronously.
+    def fetch_blocking
+      Utils.wrap_df(_inner.fetch_blocking)
+    end
+  end
+end

data/lib/polars/io/cloud.rb

@@ -0,0 +1,18 @@
+module Polars
+  module IO
+    private
+
+    def _init_credential_provider_builder(
+      credential_provider,
+      source,
+      storage_options,
+      caller_name
+    )
+      if credential_provider && credential_provider != "auto"
+        raise Todo
+      end
+
+      nil
+    end
+  end
+end