polars-df 0.10.0-x86_64-linux → 0.12.0-x86_64-linux

data/lib/polars/string_expr.rb

@@ -39,7 +39,7 @@ module Polars
     #   # ]
     def to_date(format = nil, strict: true, exact: true, cache: true)
       _validate_format_argument(format)
-      Utils.wrap_expr(self._rbexpr.str_to_date(format, strict, exact, cache))
+      Utils.wrap_expr(_rbexpr.str_to_date(format, strict, exact, cache))
     end
 
     # Convert a Utf8 column into a Datetime column.
@@ -83,14 +83,14 @@ module Polars
       strict: true,
       exact: true,
       cache: true,
-      use_earliest: nil,
       ambiguous: "raise"
     )
       _validate_format_argument(format)
-      ambiguous = Utils.rename_use_earliest_to_ambiguous(use_earliest, ambiguous)
-      ambiguous = Polars.lit(ambiguous) unless ambiguous.is_a?(Expr)
+      unless ambiguous.is_a?(Expr)
+        ambiguous = Polars.lit(ambiguous)
+      end
       Utils.wrap_expr(
-        self._rbexpr.str_to_datetime(
+        _rbexpr.str_to_datetime(
           format,
           time_unit,
           time_zone,
@@ -331,7 +331,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [1, nil, 2]})
-    #   df.select(Polars.col("foo").str.concat("-"))
+    #   df.select(Polars.col("foo").str.join("-"))
     #   # =>
     #   # shape: (1, 1)
     #   # ┌─────┐
@@ -344,7 +344,7 @@ module Polars
     #
     # @example
     #   df = Polars::DataFrame.new({"foo" => [1, nil, 2]})
-    #   df.select(Polars.col("foo").str.concat("-", ignore_nulls: false))
+    #   df.select(Polars.col("foo").str.join("-", ignore_nulls: false))
     #   # =>
     #   # shape: (1, 1)
     #   # ┌──────┐
@@ -354,9 +354,10 @@ module Polars
     #   # ╞══════╡
     #   # │ null │
     #   # └──────┘
-    def concat(delimiter = "-", ignore_nulls: true)
-      Utils.wrap_expr(_rbexpr.str_concat(delimiter, ignore_nulls))
+    def join(delimiter = "-", ignore_nulls: true)
+      Utils.wrap_expr(_rbexpr.str_join(delimiter, ignore_nulls))
     end
+    alias_method :concat, :join
 
     # Transform to uppercase variant.
     #
@@ -446,7 +447,7 @@ module Polars
     #   # │ both  │
     #   # └───────┘
     def strip_chars(characters = nil)
-      characters = Utils.parse_as_expression(characters, str_as_lit: true)
+      characters = Utils.parse_into_expression(characters, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_chars(characters))
     end
     alias_method :strip, :strip_chars
@@ -473,7 +474,7 @@ module Polars
     #   # │ both   │
     #   # └────────┘
     def strip_chars_start(characters = nil)
-      characters = Utils.parse_as_expression(characters, str_as_lit: true)
+      characters = Utils.parse_into_expression(characters, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_chars_start(characters))
     end
     alias_method :lstrip, :strip_chars_start
@@ -500,7 +501,7 @@ module Polars
     #   # │  both │
     #   # └───────┘
     def strip_chars_end(characters = nil)
-      characters = Utils.parse_as_expression(characters, str_as_lit: true)
+      characters = Utils.parse_into_expression(characters, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_chars_end(characters))
     end
     alias_method :rstrip, :strip_chars_end
@@ -530,7 +531,7 @@ module Polars
     #   # │ bar       ┆ bar      │
     #   # └───────────┴──────────┘
     def strip_prefix(prefix)
-      prefix = Utils.parse_as_expression(prefix, str_as_lit: true)
+      prefix = Utils.parse_into_expression(prefix, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_prefix(prefix))
     end
 
@@ -560,7 +561,7 @@ module Polars
     #   # │ bar       ┆          │
     #   # └───────────┴──────────┘
     def strip_suffix(suffix)
-      suffix = Utils.parse_as_expression(suffix, str_as_lit: true)
+      suffix = Utils.parse_into_expression(suffix, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_strip_suffix(suffix))
     end
 
@@ -654,7 +655,7 @@ module Polars
     #   # │ null   ┆ null   │
     #   # └────────┴────────┘
     def zfill(length)
-      length = Utils.parse_as_expression(length)
+      length = Utils.parse_into_expression(length)
       Utils.wrap_expr(_rbexpr.str_zfill(length))
     end
 
@@ -689,7 +690,7 @@ module Polars
     #   # │ null        ┆ null  ┆ null    │
     #   # └─────────────┴───────┴─────────┘
     def contains(pattern, literal: false, strict: true)
-      pattern = Utils.expr_to_lit_or_expr(pattern, str_to_lit: true)._rbexpr
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_contains(pattern, literal, strict))
     end
 
@@ -729,7 +730,7 @@ module Polars
     #   # │ mango  │
     #   # └────────┘
     def ends_with(sub)
-      sub = Utils.expr_to_lit_or_expr(sub, str_to_lit: true)._rbexpr
+      sub = Utils.parse_into_expression(sub, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_ends_with(sub))
     end
 
@@ -769,7 +770,7 @@ module Polars
     #   # │ apple  │
     #   # └────────┘
     def starts_with(sub)
-      sub = Utils.expr_to_lit_or_expr(sub, str_to_lit: true)._rbexpr
+      sub = Utils.parse_into_expression(sub, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_starts_with(sub))
     end
 
@@ -840,6 +841,7 @@ module Polars
     #   # │ true     │
     #   # └──────────┘
     def json_path_match(json_path)
+      json_path = Utils.parse_into_expression(json_path, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_json_path_match(json_path))
     end
 
@@ -939,7 +941,7 @@ module Polars
     #   # │ 678 │
     #   # └─────┘
     def extract(pattern, group_index: 1)
-      pattern = Utils.parse_as_expression(pattern, str_as_lit: true)
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_extract(pattern, group_index))
     end
 
@@ -971,8 +973,8 @@ module Polars
     #   # │ ["678", "910"] │
     #   # └────────────────┘
     def extract_all(pattern)
-      pattern = Utils.expr_to_lit_or_expr(pattern, str_to_lit: true)
-      Utils.wrap_expr(_rbexpr.str_extract_all(pattern._rbexpr))
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_extract_all(pattern))
     end
 
     # Extract all capture groups for the given regex pattern.
@@ -1018,15 +1020,15 @@ module Polars
     #   )
     #   # =>
     #   # shape: (3, 3)
-    #   # ┌───────────────────────────────────┬───────────────────────┬──────────┐
-    #   # │ url                               ┆ captures              ┆ name     │
-    #   # │ ---                               ┆ ---                   ┆ ---      │
-    #   # │ str                               ┆ struct[2]             ┆ str      │
-    #   # ╞═══════════════════════════════════╪═══════════════════════╪══════════╡
-    #   # │ http://vote.com/ballon_dor?candi… ┆ {"messi","python"}    ┆ MESSI    │
-    #   # │ http://vote.com/ballon_dor?candi… ┆ {"weghorst","polars"} ┆ WEGHORST │
-    #   # │ http://vote.com/ballon_dor?error… ┆ {null,null}           ┆ null     │
-    #   # └───────────────────────────────────┴───────────────────────┴──────────┘
+    #   # ┌─────────────────────────────────┬───────────────────────┬──────────┐
+    #   # │ url                             ┆ captures              ┆ name     │
+    #   # │ ---                             ┆ ---                   ┆ ---      │
+    #   # │ str                             ┆ struct[2]             ┆ str      │
+    #   # ╞═════════════════════════════════╪═══════════════════════╪══════════╡
+    #   # │ http://vote.com/ballon_dor?can… ┆ {"messi","python"}    ┆ MESSI    │
+    #   # │ http://vote.com/ballon_dor?can… ┆ {"weghorst","polars"} ┆ WEGHORST │
+    #   # │ http://vote.com/ballon_dor?err… ┆ {null,null}           ┆ null     │
+    #   # └─────────────────────────────────┴───────────────────────┴──────────┘
     def extract_groups(pattern)
       Utils.wrap_expr(_rbexpr.str_extract_groups(pattern))
     end
@@ -1056,7 +1058,7 @@ module Polars
     #   # │ 6            │
     #   # └──────────────┘
     def count_matches(pattern, literal: false)
-      pattern = Utils.parse_as_expression(pattern, str_as_lit: true)
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_count_matches(pattern, literal))
     end
     alias_method :count_match, :count_matches
@@ -1085,12 +1087,11 @@ module Polars
     #   # │ ["foo", "bar", "baz"] │
     #   # └───────────────────────┘
     def split(by, inclusive: false)
-      by = Utils.parse_as_expression(by, str_as_lit: true)
+      by = Utils.parse_into_expression(by, str_as_lit: true)
       if inclusive
-        Utils.wrap_expr(_rbexpr.str_split_inclusive(by))
-      else
-        Utils.wrap_expr(_rbexpr.str_split(by))
+        return Utils.wrap_expr(_rbexpr.str_split_inclusive(by))
       end
+      Utils.wrap_expr(_rbexpr.str_split(by))
     end
 
     # Split the string by a substring using `n` splits.
@@ -1128,7 +1129,7 @@ module Polars
     #   # │ {"d","4"}   │
     #   # └─────────────┘
     def split_exact(by, n, inclusive: false)
-      by = Utils.parse_as_expression(by, str_as_lit: true)
+      by = Utils.parse_into_expression(by, str_as_lit: true)
       if inclusive
         Utils.wrap_expr(_rbexpr.str_split_exact_inclusive(by, n))
       else
@@ -1165,7 +1166,7 @@ module Polars
     #   # │ {"foo","bar baz"} │
     #   # └───────────────────┘
     def splitn(by, n)
-      by = Utils.parse_as_expression(by, str_as_lit: true)
+      by = Utils.parse_into_expression(by, str_as_lit: true)
       Utils.wrap_expr(_rbexpr.str_splitn(by, n))
     end
 
@@ -1196,9 +1197,9 @@ module Polars
     #   # │ 2   ┆ abc456 │
     #   # └─────┴────────┘
     def replace(pattern, value, literal: false, n: 1)
-      pattern = Utils.expr_to_lit_or_expr(pattern, str_to_lit: true)
-      value = Utils.expr_to_lit_or_expr(value, str_to_lit: true)
-      Utils.wrap_expr(_rbexpr.str_replace_n(pattern._rbexpr, value._rbexpr, literal, n))
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
+      value = Utils.parse_into_expression(value, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_replace_n(pattern, value, literal, n))
     end
 
     # Replace all matching regex/literal substrings with a new string value.
@@ -1226,9 +1227,9 @@ module Polars
     #   # │ 2   ┆ 123-123 │
     #   # └─────┴─────────┘
     def replace_all(pattern, value, literal: false)
-      pattern = Utils.expr_to_lit_or_expr(pattern, str_to_lit: true)
-      value = Utils.expr_to_lit_or_expr(value, str_to_lit: true)
-      Utils.wrap_expr(_rbexpr.str_replace_all(pattern._rbexpr, value._rbexpr, literal))
+      pattern = Utils.parse_into_expression(pattern, str_as_lit: true)
+      value = Utils.parse_into_expression(value, str_as_lit: true)
+      Utils.wrap_expr(_rbexpr.str_replace_all(pattern, value, literal))
     end
 
     # Returns string values in reversed order.
@@ -1281,36 +1282,11 @@ module Polars
     #   # │ dragonfruit ┆ uit      │
     #   # └─────────────┴──────────┘
     def slice(offset, length = nil)
-      offset = Utils.parse_as_expression(offset)
-      length = Utils.parse_as_expression(length)
+      offset = Utils.parse_into_expression(offset)
+      length = Utils.parse_into_expression(length)
       Utils.wrap_expr(_rbexpr.str_slice(offset, length))
     end
 
-    # Returns a column with a separate row for every string character.
-    #
-    # @return [Expr]
-    #
-    # @example
-    #   df = Polars::DataFrame.new({"a": ["foo", "bar"]})
-    #   df.select(Polars.col("a").str.explode)
-    #   # =>
-    #   # shape: (6, 1)
-    #   # ┌─────┐
-    #   # │ a   │
-    #   # │ --- │
-    #   # │ str │
-    #   # ╞═════╡
-    #   # │ f   │
-    #   # │ o   │
-    #   # │ o   │
-    #   # │ b   │
-    #   # │ a   │
-    #   # │ r   │
-    #   # └─────┘
-    def explode
-      Utils.wrap_expr(_rbexpr.str_explode)
-    end
-
     # Convert an Utf8 column into an Int64 column with base radix.
     #
     # @param base [Integer]
@@ -1354,7 +1330,7 @@ module Polars
     #   # │ null ┆ null   │
     #   # └──────┴────────┘
     def to_integer(base: 10, strict: true)
-      base = Utils.parse_as_expression(base, str_as_lit: false)
+      base = Utils.parse_into_expression(base, str_as_lit: false)
       Utils.wrap_expr(_rbexpr.str_to_integer(base, strict))
     end
 
@@ -1418,17 +1394,17 @@ module Polars
     #   )
     #   # =>
     #   # shape: (3, 2)
-    #   # ┌───────────────────────────────────┬──────────────┐
-    #   # │ lyrics                            ┆ contains_any │
-    #   # │ ---                               ┆ ---          │
-    #   # │ str                               ┆ bool         │
-    #   # ╞═══════════════════════════════════╪══════════════╡
-    #   # │ Everybody wants to rule the worl… ┆ false        │
-    #   # │ Tell me what you want, what you … ┆ true         │
-    #   # │ Can you feel the love tonight     ┆ true         │
-    #   # └───────────────────────────────────┴──────────────┘
+    #   # ┌─────────────────────────────────┬──────────────┐
+    #   # │ lyrics                          ┆ contains_any │
+    #   # │ ---                             ┆ ---          │
+    #   # │ str                             ┆ bool         │
+    #   # ╞═════════════════════════════════╪══════════════╡
+    #   # │ Everybody wants to rule the wo… ┆ false        │
+    #   # │ Tell me what you want, what yo… ┆ true         │
+    #   # │ Can you feel the love tonight   ┆ true         │
+    #   # └─────────────────────────────────┴──────────────┘
     def contains_any(patterns, ascii_case_insensitive: false)
-      patterns = Utils.parse_as_expression(patterns, str_as_lit: false, list_as_lit: false)
+      patterns = Utils.parse_into_expression(patterns, str_as_lit: false, list_as_series: true)
       Utils.wrap_expr(
         _rbexpr.str_contains_any(patterns, ascii_case_insensitive)
       )
@@ -1468,15 +1444,15 @@ module Polars
     #   )
     #   # =>
     #   # shape: (3, 2)
-    #   # ┌───────────────────────────────────┬───────────────────────────────────┐
-    #   # │ lyrics                            ┆ removes_pronouns                  │
-    #   # │ ---                               ┆ ---                               │
-    #   # │ str                               ┆ str                               │
-    #   # ╞═══════════════════════════════════╪═══════════════════════════════════╡
-    #   # │ Everybody wants to rule the worl… ┆ Everybody wants to rule the worl… │
-    #   # │ Tell me what you want, what you … ┆ Tell  what  want, what  really r… │
-    #   # │ Can you feel the love tonight     ┆ Can  feel the love tonight        │
-    #   # └───────────────────────────────────┴───────────────────────────────────┘
+    #   # ┌─────────────────────────────────┬─────────────────────────────────┐
+    #   # │ lyrics                          ┆ removes_pronouns                │
+    #   # │ ---                             ┆ ---                             │
+    #   # │ str                             ┆ str                             │
+    #   # ╞═════════════════════════════════╪═════════════════════════════════╡
+    #   # │ Everybody wants to rule the wo… ┆ Everybody wants to rule the wo… │
+    #   # │ Tell me what you want, what yo… ┆ Tell  what  want, what  really… │
+    #   # │ Can you feel the love tonight   ┆ Can  feel the love tonight      │
+    #   # └─────────────────────────────────┴─────────────────────────────────┘
     #
     # @example
     #   df.with_columns(
@@ -1489,19 +1465,19 @@ module Polars
     #   )
     #   # =>
     #   # shape: (3, 2)
-    #   # ┌───────────────────────────────────┬───────────────────────────────────┐
-    #   # │ lyrics                            ┆ confusing                         │
-    #   # │ ---                               ┆ ---                               │
-    #   # │ str                               ┆ str                               │
-    #   # ╞═══════════════════════════════════╪═══════════════════════════════════╡
-    #   # │ Everybody wants to rule the worl… ┆ Everybody wants to rule the worl… │
-    #   # │ Tell me what you want, what you … ┆ Tell you what me want, what me r… │
-    #   # │ Can you feel the love tonight     ┆ Can me feel the love tonight      │
-    #   # └───────────────────────────────────┴───────────────────────────────────┘
+    #   # ┌─────────────────────────────────┬─────────────────────────────────┐
+    #   # │ lyrics                          ┆ confusing                       │
+    #   # │ ---                             ┆ ---                             │
+    #   # │ str                             ┆ str                             │
+    #   # ╞═════════════════════════════════╪═════════════════════════════════╡
+    #   # │ Everybody wants to rule the wo… ┆ Everybody wants to rule the wo… │
+    #   # │ Tell me what you want, what yo… ┆ Tell you what me want, what me… │
+    #   # │ Can you feel the love tonight   ┆ Can me feel the love tonight    │
+    #   # └─────────────────────────────────┴─────────────────────────────────┘
     def replace_many(patterns, replace_with, ascii_case_insensitive: false)
-      patterns = Utils.parse_as_expression(patterns, str_as_lit: false, list_as_lit: false)
-      replace_with = Utils.parse_as_expression(
-        replace_with, str_as_lit: true, list_as_lit: false
+      patterns = Utils.parse_into_expression(patterns, str_as_lit: false, list_as_series: true)
+      replace_with = Utils.parse_into_expression(
+        replace_with, str_as_lit: true, list_as_series: true
       )
       Utils.wrap_expr(
         _rbexpr.str_replace_many(

data/lib/polars/string_name_space.rb

@@ -83,7 +83,7 @@ module Polars
       strict: true,
       exact: true,
       cache: true,
-      use_earliest: nil
+      ambiguous: "raise"
     )
       super
     end
@@ -233,7 +233,7 @@ module Polars
     # @return [Series]
     #
     # @example
-    #   Polars::Series.new([1, nil, 2]).str.concat("-")
+    #   Polars::Series.new([1, nil, 2]).str.join("-")
     #   # =>
     #   # shape: (1,)
     #   # Series: '' [str]
@@ -242,16 +242,17 @@ module Polars
     #   # ]
     #
     # @example
-    #   Polars::Series.new([1, nil, 2]).str.concat("-", ignore_nulls: false)
+    #   Polars::Series.new([1, nil, 2]).str.join("-", ignore_nulls: false)
     #   # =>
     #   # shape: (1,)
     #   # Series: '' [str]
     #   # [
     #   #         null
     #   # ]
-    def concat(delimiter = "-", ignore_nulls: true)
+    def join(delimiter = "-", ignore_nulls: true)
       super
     end
+    alias_method :concat, :join
 
     # Check if strings in Series contain a substring that matches a regex.
     #

data/lib/polars/testing.rb

@@ -271,9 +271,9 @@ module Polars
 
     def _assert_correct_input_type(left, right)
       if left.is_a?(DataFrame) && right.is_a?(DataFrame)
-        return false
+        false
       elsif left.is_a?(LazyFrame) && right.is_a?(DataFrame)
-        return true
+        true
       else
         raise_assertion_error(
           "inputs",

data/lib/polars/utils/constants.rb

@@ -0,0 +1,9 @@
+module Polars
+  module Utils
+    SECONDS_PER_DAY = 86_400
+    SECONDS_PER_HOUR = 3_600
+    NS_PER_SECOND = 1_000_000_000
+    US_PER_SECOND = 1_000_000
+    MS_PER_SECOND = 1_000
+  end
+end

data/lib/polars/utils/convert.rb

@@ -0,0 +1,97 @@
+module Polars
+  module Utils
+    def self.parse_as_duration_string(td)
+      if td.nil? || td.is_a?(::String)
+        return td
+      end
+      _timedelta_to_duration_string(td)
+    end
+
+    def self._timedelta_to_pl_duration(td)
+      td
+    end
+
+    def self.negate_duration_string(duration)
+      if duration.start_with?("-")
+        duration[1..]
+      else
+        "-#{duration}"
+      end
+    end
+
+    def self.date_to_int(d)
+      dt = d.to_datetime.to_time
+      dt.to_i / SECONDS_PER_DAY
+    end
+
+    def self.datetime_to_int(dt, time_unit)
+      dt = dt.to_datetime.to_time
+      if time_unit == "ns"
+        nanos = dt.nsec
+        dt.to_i * NS_PER_SECOND + nanos
+      elsif time_unit == "us"
+        micros = dt.usec
+        dt.to_i * US_PER_SECOND + micros
+      elsif time_unit == "ms"
+        millis = dt.usec / 1000
+        dt.to_i * MS_PER_SECOND + millis
+      elsif time_unit.nil?
+        # Ruby has ns precision
+        nanos = dt.nsec
+        dt.to_i * NS_PER_SECOND + nanos
+      else
+        raise ArgumentError, "time_unit must be one of {{'ns', 'us', 'ms'}}, got #{tu}"
+      end
+    end
+
+    def self._to_ruby_date(value)
+      # days to seconds
+      # important to create from utc. Not doing this leads
+      # to inconsistencies dependent on the timezone you are in.
+      ::Time.at(value * 86400).utc.to_date
+    end
+
+    def self._to_ruby_time(value)
+      if value == 0
+        ::Time.utc(2000, 1, 1)
+      else
+        seconds, nanoseconds = value.divmod(1_000_000_000)
+        minutes, seconds = seconds.divmod(60)
+        hours, minutes = minutes.divmod(60)
+        ::Time.utc(2000, 1, 1, hours, minutes, seconds, nanoseconds / 1000.0)
+      end
+    end
+
+    def self._to_ruby_datetime(value, time_unit = "ns", time_zone = nil)
+      if time_zone.nil? || time_zone == "" || time_zone == "UTC"
+        if time_unit == "ns"
+          ::Time.at(value / 1000000000, value % 1000000000, :nsec).utc
+        elsif time_unit == "us"
+          ::Time.at(value / 1000000, value % 1000000, :usec).utc
+        elsif time_unit == "ms"
+          ::Time.at(value / 1000, value % 1000, :millisecond).utc
+        else
+          raise ArgumentError, "time_unit must be one of {{'ns', 'us', 'ms'}}, got #{time_unit}"
+        end
+      else
+        raise Todo
+      end
+    end
+
+    def self._to_ruby_duration(value, time_unit = "ns")
+      if time_unit == "ns"
+        value / 1e9
+      elsif time_unit == "us"
+        value / 1e6
+      elsif time_unit == "ms"
+        value / 1e3
+      else
+        raise ArgumentError, "time_unit must be one of {{'ns', 'us', 'ms'}}, got #{time_unit}"
+      end
+    end
+
+    def self._to_ruby_decimal(digits, scale)
+      BigDecimal("#{digits}e#{scale}")
+    end
+  end
+end

data/lib/polars/utils/parse.rb

@@ -0,0 +1,89 @@
+module Polars
+  module Utils
+    def self.parse_into_expression(
+      input,
+      str_as_lit: false,
+      list_as_series: false,
+      structify: false,
+      dtype: nil
+    )
+      if input.is_a?(Expr)
+        expr = input
+        if structify
+          expr = _structify_expression(expr)
+        end
+      elsif (input.is_a?(::String) || input.is_a?(Symbol)) && !str_as_lit
+        expr = F.col(input)
+      elsif input.is_a?(::Array) && list_as_series
+        expr = F.lit(Series.new(input), dtype: dtype)
+      else
+        expr = F.lit(input, dtype: dtype)
+      end
+
+      expr._rbexpr
+    end
+
+    def self.parse_into_list_of_expressions(*inputs, __structify: false, **named_inputs)
+      exprs = _parse_positional_inputs(inputs, structify: __structify)
+      if named_inputs.any?
+        named_exprs = _parse_named_inputs(named_inputs, structify: __structify)
+        exprs.concat(named_exprs)
+      end
+
+      exprs
+    end
+
+    def self._parse_positional_inputs(inputs, structify: false)
+      inputs_iter = _parse_inputs_as_iterable(inputs)
+      inputs_iter.map { |e| parse_into_expression(e, structify: structify) }
+    end
+
+    def self._parse_inputs_as_iterable(inputs)
+      if inputs.empty?
+        return []
+      end
+
+      if inputs.length == 1 && inputs[0].is_a?(::Array)
+        return inputs[0]
+      end
+
+      inputs
+    end
+
+    def self._parse_named_inputs(named_inputs, structify: false)
+      named_inputs.map do |name, input|
+        parse_into_expression(input, structify: structify)._alias(name.to_s)
+      end
+    end
+
+    def self.parse_predicates_constraints_into_expression(*predicates, **constraints)
+      all_predicates = _parse_positional_inputs(predicates)
+
+      if constraints.any?
+        constraint_predicates = _parse_constraints(constraints)
+        all_predicates.concat(constraint_predicates)
+      end
+
+      _combine_predicates(all_predicates)
+    end
+
+    def self._parse_constraints(constraints)
+      constraints.map do |name, value|
+        Polars.col(name).eq(value)._rbexpr
+      end
+    end
+
+    def self._combine_predicates(predicates)
+      if !predicates.any?
+        msg = "at least one predicate or constraint must be provided"
+        raise TypeError, msg
+      end
+
+      if predicates.length == 1
+        return predicates[0]
+      end
+
+      Plr.all_horizontal(predicates)
+    end
+  end
+end